@k2b/cloud 0.45.0 → 0.46.0

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);

package/src/contracts/capabilities.ts

@@ -13,6 +13,7 @@ import type { RequestAuthority } from "../server/middleware/auth";
 import type { AppEventDefinition, AppEventSubscriptionDefinition } from "./app-events";
 import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";
+import { AuthenticatedPrincipalSchema } from "./shared";
 
 export const CAPABILITY_PROTOCOL_VERSION = 2 as const;
 export const CAPABILITY_MAX_REQUEST_BYTES = 256 * 1024;
@@ -121,6 +122,38 @@ export const CloudResourceReferenceSchema = CloudResourceRefSchema.extend({
 
 export type CloudResourceReference = z.infer<typeof CloudResourceReferenceSchema>;
 
+/** Authorized presentation returned as `data.view` by a canonical resource reader. */
+export const CloudResourceReaderViewSchema = z
+  .object({
+    title: z.string().min(1).max(500),
+    context: CloudResourceReferenceSchema.shape.context,
+    status: CloudResourceReferenceSchema.shape.status,
+    done: z.boolean().optional(),
+    permission: z.enum(["read", "write", "admin"]),
+    container: z
+      .object({ ref: CloudResourceRefSchema, title: z.string().min(1).max(500) })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type CloudResourceReaderView = z.infer<typeof CloudResourceReaderViewSchema>;
+
+/** Concrete accounts, reusing the grant principal identities; never a group or wildcard. */
+export const ResourcePrincipalSchema = z.discriminatedUnion("type", [
+  AuthenticatedPrincipalSchema.options[0].strict(),
+  AuthenticatedPrincipalSchema.options[2].strict(),
+]);
+export type ResourcePrincipal = z.infer<typeof ResourcePrincipalSchema>;
+export const ResourceReadableInputSchema = z
+  .object({
+    id: CloudResourceRefSchema.shape.id,
+    container: CloudResourceRefSchema.optional().describe("Expected current container; required for a contained type."),
+    principals: z.array(ResourcePrincipalSchema).max(500).describe("Concrete accounts whose current resource readability is checked."),
+  })
+  .strict();
+export type ResourceReadableInput = z.output<typeof ResourceReadableInputSchema>;
+export const ResourceReadableDataSchema = z.object({ readable: z.array(ResourcePrincipalSchema).max(500) }).strict();
+
 // Consumer permalinks may encode all 512 UTF-16 units of an id (up to 4,608 characters).
 export const CloudResourceHrefSchema = z.string().min(1).max(8192).regex(CLOUD_PATH_PATTERN);
 
@@ -832,6 +865,15 @@ export type CapabilityResourceTypeDefinition = {
   /** One colour per kind of resource, so a card or list shows at a glance what it stands for. */
   color?: CapabilityResourceColor;
   reader?: string;
+  /** Local type in the same application. Describes containment, never inherited authority. */
+  container?: string;
+  access?: {
+    /** Return only readable input principals, using current grants and account status, never credential scopes. */
+    readable?: (
+      input: ResourceReadableInput,
+      context: CapabilityAppExecutionContext,
+    ) => readonly ResourcePrincipal[] | Promise<readonly ResourcePrincipal[]>;
+  };
   /** Root-relative pages recognized when a person pastes a Cloud link. Requires a reader. */
   pages?: readonly string[];
 };
@@ -911,7 +953,23 @@ export type CapabilityPresentationCatalog = {
   translations: Readonly<Record<string, CapabilityPresentationTranslation>>;
 };
 
+/** App authority has no grant-bearing subject, user, nested exchange, or interactive credential. */
+export type CapabilityAppExecutionContext = {
+  actor: { kind: "app"; appId: string };
+  accessSubject: { type: "none" };
+  user: null;
+  authority?: never;
+  query?: never;
+  idempotencyKey?: never;
+  locale: string;
+  requestId: string;
+  origin: CapabilityOrigin;
+  via?: CapabilityVia;
+  signal: AbortSignal;
+};
+
 export type CapabilityQueryDefinition<Input extends z.ZodType = z.ZodType<any>, Data extends z.ZodType = z.ZodType<any>> = {
+  appOnly?: never;
   title: string;
   description: string;
   input: Input;
@@ -929,6 +987,7 @@ export type CapabilityIdempotencyPolicy = "none" | "required";
 export type CapabilityActionApprovalPolicy = "rememberable" | "none";
 
 export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>, Data extends z.ZodType = z.ZodType<any>> = {
+  appOnly?: never;
   title: string;
   description: string;
   input: Input;
@@ -980,6 +1039,8 @@ export type CapabilityFileProviderDeclaration = { list: string; read: string; sa
 
 export type CapabilityCalendarSourceDeclaration = { calendars: string; events: string; update?: string; move?: string; delete?: string };
 
+export type CapabilityDiscussionsDeclaration = { item: string; containers: string; activity?: string };
+
 export type CapabilityDefinitions = {
   protocolVersion: typeof CAPABILITY_PROTOCOL_VERSION;
   presentation?: CapabilityPresentationCatalog;
@@ -989,6 +1050,7 @@ export type CapabilityDefinitions = {
   commands?: CapabilityDefinitionCatalog<CapabilityCommandDefinition>;
   fileProvider?: CapabilityFileProviderDeclaration;
   calendarSource?: CapabilityCalendarSourceDeclaration;
+  discussions?: CapabilityDiscussionsDeclaration;
   events?: CapabilityDefinitionCatalog<AppEventDefinition>;
   subscribes?: CapabilityDefinitionCatalog<AppEventSubscriptionDefinition>;
 };
@@ -1044,6 +1106,7 @@ const CapabilityOperationManifestBaseSchema = z
   .strict();
 
 export const CapabilityQueryManifestSchema = CapabilityOperationManifestBaseSchema.extend({
+  appOnly: z.literal(true).optional(),
   openWorld: z.boolean(),
   universalSearch: z
     .object({ tags: z.array(CapabilitySearchTagManifestSchema).max(100), scopeTypes: z.array(CapabilityLocalIdSchema).max(100).optional() })
@@ -1116,6 +1179,24 @@ export const CapabilityResourcePageManifestSchema = z
   })
   .strict();
 
+export const CapabilityDiscussionsManifestSchema = z
+  .object({
+    item: CapabilityLocalIdSchema,
+    containers: CapabilityLocalIdSchema,
+    activity: CapabilityLocalIdSchema.optional(),
+  })
+  .strict();
+export const CapabilityResourceTypeModelSchema = z
+  .object({
+    type: CapabilityLocalIdSchema,
+    container: CapabilityLocalIdSchema.optional(),
+    view: z.literal(true).optional(),
+    /** Availability claim, retained in person catalogs even though the generated query is hidden. */
+    readable: z.literal(true).optional(),
+  })
+  .strict();
+export type CapabilityResourceTypeModel = z.infer<typeof CapabilityResourceTypeModelSchema>;
+
 /** Keeps the sent entries this release reads completely. */
 const readEntries = <T extends z.ZodType>(values: unknown, entry: T): z.output<T>[] | null => {
   // Not a bounded list: leave the value to the manifest schema, which rejects it.
@@ -1146,7 +1227,7 @@ const readEntries = <T extends z.ZodType>(values: unknown, entry: T): z.output<T
  * pages and pages without a readable Type/reader are omitted; live prefix ownership is checked separately.
  * Every other entry stays available.
  */
-const readableManifest = (value: unknown): unknown => {
+const readableManifest = (value: unknown, personCatalog = false): unknown => {
   if (!value || typeof value !== "object" || Array.isArray(value)) return value;
   const sent = value as Record<string, unknown>;
   const types = readEntries(sent.types, CapabilityResourceTypeManifestSchema);
@@ -1180,7 +1261,54 @@ const readableManifest = (value: unknown): unknown => {
     policies[action.localId] = policy;
     return true;
   });
-  const { calendarSource: sentCalendarSource, fileProvider: sentProvider, policies: _policies, resourcePages: sentPages, ...rest } = sent;
+  const {
+    calendarSource: sentCalendarSource,
+    fileProvider: sentProvider,
+    policies: _policies,
+    resourcePages: sentPages,
+    resourceTypes: sentModels,
+    discussions: sentDiscussions,
+    ...rest
+  } = sent;
+  const models = readEntries(sentModels ?? [], CapabilityResourceTypeModelSchema) ?? [];
+  const resourceTypes = models.flatMap((model) => {
+    const type = types.find((type) => type.localId === model.type);
+    if (!type || (model.container && !typeIds.has(model.container))) return [];
+    const seen = new Set([model.type]);
+    let parent = model.container;
+    while (parent) {
+      if (seen.has(parent)) return [];
+      seen.add(parent);
+      parent = models.find((candidate) => candidate.type === parent)?.container;
+    }
+    if (models.filter((candidate) => candidate.type === model.type).length !== 1) return [];
+    const { view, readable, ...rest } = model;
+    return [
+      {
+        ...rest,
+        ...(readable &&
+        (readableQueries.some((query) => query.localId === `${model.type}.readable` && query.appOnly === true) ||
+          // Core validates the full manifest before hiding app-only queries from person catalogs.
+          (personCatalog &&
+            Array.isArray(sent.queries) &&
+            !sent.queries.some(
+              (query: unknown) =>
+                typeof query === "object" && query !== null && "localId" in query && query.localId === `${model.type}.readable`,
+            )))
+          ? { readable }
+          : {}),
+        ...(view && type.reader && queryIds.has(type.reader) ? { view } : {}),
+      },
+    ];
+  });
+  const role = CapabilityDiscussionsManifestSchema.safeParse(sentDiscussions);
+  const discussions =
+    role.success &&
+    typeIds.has(role.data.item) &&
+    queryIds.has(role.data.containers) &&
+    (!role.data.activity || queryIds.has(role.data.activity))
+      ? role.data
+      : undefined;
   const provider = CapabilityFileProviderManifestSchema.safeParse(sentProvider);
   const calendar = CapabilityCalendarSourceManifestSchema.safeParse(sentCalendarSource);
   const pageCounts = new Map<string, number>();
@@ -1198,6 +1326,8 @@ const readableManifest = (value: unknown): unknown => {
       : [];
   return {
     ...rest,
+    ...(sentModels !== undefined ? { resourceTypes } : {}),
+    ...(discussions ? { discussions } : {}),
     ...(sentPages !== undefined ? { resourcePages } : {}),
     ...(provider.success ? { fileProvider: provider.data } : {}),
     ...(calendar.success ? { calendarSource: calendar.data } : {}),
@@ -1228,7 +1358,7 @@ const readableManifest = (value: unknown): unknown => {
  * Producers stay strict: `app.start()` registers exactly the manifest its release defines.
  */
 export const CapabilityManifestSchema = z.preprocess(
-  readableManifest,
+  (value) => readableManifest(value),
   z.object({
     protocolVersion: z.literal(CAPABILITY_PROTOCOL_VERSION),
     appId: CapabilityAppIdSchema,
@@ -1240,6 +1370,8 @@ export const CapabilityManifestSchema = z.preprocess(
     // Optional without a default: a manifest without a provider keeps the shape and hash of earlier releases.
     fileProvider: CapabilityFileProviderManifestSchema.optional(),
     calendarSource: CapabilityCalendarSourceManifestSchema.optional(),
+    discussions: CapabilityDiscussionsManifestSchema.optional(),
+    resourceTypes: z.array(CapabilityResourceTypeModelSchema).max(MAX_MANIFEST_ENTRIES).optional(),
     policies: z.record(CapabilityLocalIdSchema, CapabilityActionPolicySchema).optional(),
     events: z.array(CapabilityEventManifestSchema).max(MAX_MANIFEST_ENTRIES).optional(),
     subscribes: z.array(CapabilitySubscriptionManifestSchema).max(MAX_MANIFEST_ENTRIES).optional(),
@@ -1297,7 +1429,8 @@ export const CapabilityCatalogAppSchema = z.object({
   appName: z.string().min(1).max(200),
   appIcon: z.string().min(1).max(120),
   appDescription: z.string().max(1000),
-  manifest: CapabilityManifestSchema,
+  // This is Core's person projection, whose app-only queries have already been hidden.
+  manifest: z.preprocess((value) => readableManifest(value, true), CapabilityManifestSchema.out),
   events: z.array(CapabilityEventCatalogEntrySchema).max(MAX_MANIFEST_ENTRIES).optional(),
 });
 

package/src/contracts/discussions.ts

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { type CapabilityManifest, CapabilitySemanticLinkSchema, CloudResourceRefSchema } from "./capabilities";
+import { type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+import { typeViewIssues } from "./resource-types";
+
+/** Same page bound as resource lists and owner activity pages. */
+export const DISCUSSION_PAGE_LIMIT = 100;
+const cursor = z.string().min(1).max(2048).describe("Opaque continuation cursor.");
+export const DiscussionContainersInputSchema = z
+  .object({
+    query: z.string().max(500).optional().describe("Optional container search text."),
+    cursor: cursor.optional(),
+    limit: z.number().int().min(1).max(DISCUSSION_PAGE_LIMIT).default(50).describe("Maximum containers in this page."),
+  })
+  .strict();
+export const DiscussionContainerSchema = z
+  .object({
+    ref: CloudResourceRefSchema,
+    title: z.string().min(1).max(500),
+  })
+  .strict();
+export const DiscussionContainersDataSchema = z
+  .object({
+    items: z.array(DiscussionContainerSchema).max(DISCUSSION_PAGE_LIMIT),
+    next: cursor.nullable(),
+  })
+  .strict();
+
+/** Shared owner activity, independent of the application or discussion consumer. */
+export const ResourceActivityEventSchema = z.object({
+  id: z.string().max(100),
+  at: z.string().datetime({ offset: true }),
+  ref: CloudResourceRefSchema.strip().nullable(),
+  title: z.string().max(500).nullable().optional(),
+  actor: z.object({ type: z.enum(["user", "service_account", "system"]), id: z.uuid().nullable(), name: z.string().max(1000) }),
+  icon: z
+    .string()
+    .regex(/^ti ti-[a-z0-9-]+$/)
+    .max(80),
+  sentence: z.string().max(4000),
+  href: CapabilitySemanticLinkSchema.shape.href.optional(),
+  count: z.number().int().min(1),
+});
+export type ResourceActivityEvent = z.infer<typeof ResourceActivityEventSchema>;
+export const DiscussionActivityInputSchema = z
+  .object({
+    container: CloudResourceRefSchema.shape.id.describe("Container whose authorized activity is requested."),
+    item: CloudResourceRefSchema.shape.id.optional().describe("Optional item inside that container."),
+    timeZone: z.string().min(1).max(200).optional().describe("IANA display time zone."),
+    before: z.string().datetime({ offset: true }).optional().describe("Exclusive upper timestamp bound."),
+    after: z.string().datetime({ offset: true }).optional().describe("Exclusive lower timestamp bound."),
+    cursor: cursor.optional(),
+    limit: z.number().int().min(1).max(DISCUSSION_PAGE_LIMIT).default(50).describe("Maximum events in this page."),
+  })
+  .strict();
+export const DiscussionActivityDataSchema = z.array(ResourceActivityEventSchema).max(DISCUSSION_PAGE_LIMIT);
+// The wire contract accepts additive fields; the public consumer schema strips them.
+// Zod's output JSON Schema is closed even for stripping objects, so use an explicit
+// open acceptance shape here rather than treating stripped fields as forbidden.
+const DiscussionActivityWireSchema = z
+  .array(
+    ResourceActivityEventSchema.loose().extend({
+      actor: ResourceActivityEventSchema.shape.actor.loose(),
+      ref: CloudResourceRefSchema.loose().nullable(),
+    }),
+  )
+  .max(DISCUSSION_PAGE_LIMIT);
+export type DiscussionContainer = z.infer<typeof DiscussionContainerSchema>;
+
+/** Startup/registry check: discovery is never permission to read content. */
+export const discussionsIssues = (manifest: CapabilityManifest): CapabilityContractIssue[] => {
+  const role = manifest.discussions;
+  if (!role) return [];
+  const model = manifest.resourceTypes?.find((model) => model.type === role.item);
+  const issues: CapabilityContractIssue[] = [];
+  if (!model?.container) issues.push({ code: "kind", path: "$.item", message: "Discussion item must have a container type" });
+  for (const localId of [role.item, ...(model?.container ? [model.container] : [])]) issues.push(...typeViewIssues(manifest, localId));
+  for (const [localId, input, data] of [
+    [role.containers, DiscussionContainersInputSchema, DiscussionContainersDataSchema],
+    ...(role.activity ? [[role.activity, DiscussionActivityInputSchema, DiscussionActivityWireSchema] as const] : []),
+  ] as const) {
+    const query = manifest.queries.find((query) => query.localId === localId);
+    if (!query) issues.push({ code: "kind", path: "$", message: `Missing discussion Query ${localId}` });
+    else {
+      issues.push(...capabilityContractIssues({ kind: "query", input, data }, { kind: "query", operation: query }));
+      if (query.appOnly || query.openWorld)
+        issues.push({ code: "kind", path: "$", message: `Discussion Query ${localId} must be closed-world and person-readable` });
+    }
+  }
+  return issues;
+};

package/src/contracts/geo-document.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { GeoPlaceSchema, GeoPointSchema, GeoProvenanceSchema } from "./geo";
+import { GeoRouteSchema } from "./geo-route";
+
+// One place.search result fits a saved map. Routes carry their own bounded stops.
+export const GEO_DOCUMENT_MAX_PINS = 20;
+const shortId = z.string().regex(/^[A-Za-z0-9]{6}$/);
+const label = z.string().trim().min(1).max(300);
+export const GeoDocumentLinkSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("url"), url: z.url({ protocol: /^https?$/ }).max(2000), label }).strict(),
+  z.object({ type: z.literal("note"), noteId: shortId, label }).strict(),
+  z.object({ type: z.literal("heading"), noteId: shortId, heading: z.string().min(1).max(300), label }).strict(),
+]);
+export const GeoDocumentPinSchema = z
+  .object({
+    id: GeoPlaceSchema.shape.id,
+    label,
+    point: GeoPointSchema,
+    provenance: GeoProvenanceSchema,
+    link: GeoDocumentLinkSchema.optional(),
+  })
+  .strict();
+export const GeoDocumentSchema = z
+  .object({
+    version: z.literal(1),
+    title: label,
+    savedAt: z.iso.datetime().optional(),
+    pins: z.array(GeoDocumentPinSchema).max(GEO_DOCUMENT_MAX_PINS),
+    route: GeoRouteSchema.optional(),
+  })
+  .strict()
+  .superRefine((document, context) => {
+    // Each coordinate consists of up to ten continuation bytes and one terminator.
+    // Complete latitude/longitude pairs keep malformed authored geometry out of map renderers.
+    if (document.route && !/^(?:[_-~]{0,10}[?-^][_-~]{0,10}[?-^])+$/.test(document.route.polyline6)) {
+      context.addIssue({
+        code: "custom",
+        path: ["route", "polyline6"],
+        message: "Route geometry must contain complete polyline6 coordinate pairs.",
+      });
+    }
+    const ids = new Set<string>();
+    document.pins.forEach((pin, index) => {
+      if (ids.has(pin.id)) context.addIssue({ code: "custom", path: ["pins", index, "id"], message: "Pin IDs must be unique." });
+      ids.add(pin.id);
+    });
+  });
+export type GeoDocument = z.infer<typeof GeoDocumentSchema>;
+export type GeoDocumentPin = z.infer<typeof GeoDocumentPinSchema>;
+export type GeoDocumentLink = z.infer<typeof GeoDocumentLinkSchema>;
+
+/** A portable Notebook block. Escaped JSON cannot close the directive or create HTML. */
+export function serializeGeoDocument(input: GeoDocument): string {
+  const document = GeoDocumentSchema.parse(input);
+  const json = JSON.stringify(document).replace(
+    /[<>&\u2028\u2029]/g,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+  return `:::map\n${json}\n:::`;
+}