@k2b/cloud 0.45.0 → 0.47.0

package/src/config/define-env.ts

@@ -4,10 +4,12 @@
  * Every runtime environment variable is declared once with a schema, a
  * default, a scope and a one-sentence doc. Registries read `process.env`
  * lazily: each key is parsed on access, so tests can change variables and
- * consumers never depend on an import-time snapshot. `.env.example`,
+ * consumers never depend on an import-time snapshot. Configured secret files
+ * are also validated when the registry is created. `.env.example`,
  * `.env.prod.example` and the configuration reference are generated from the
  * `$specs` of every registry by `scripts/generate-config-docs.ts`.
  */
+import { readFileSync } from "node:fs";
 import { z } from "zod";
 
 /**
@@ -17,7 +19,7 @@ import { z } from "zod";
 export type EnvScope = "runtime" | "secret" | "development";
 
 export type EnvSpec<T> = {
-  /** Parses the trimmed raw value. Empty and unset values never reach the schema. */
+  /** Parses the raw value (trimmed for env, one trailing newline removed for files). Empty and unset values never reach the schema. */
   schema: z.ZodType<T, unknown>;
   /** Used when the variable is unset or empty; a function is evaluated on every access. */
   default?: T | (() => T);
@@ -31,6 +33,8 @@ export type EnvSpec<T> = {
   required?: boolean;
   /** Alternative variable names, consulted after the canonical key. */
   aliases?: string[];
+  /** Allow NAME_FILE to supply the secret. Configured files are validated when the registry is created. */
+  secretFile?: boolean;
 };
 
 export type EnvSpecs = Record<string, EnvSpec<unknown>>;
@@ -42,20 +46,59 @@ type EnvValue<S extends EnvSpec<unknown>> = S extends { default: unknown } | { r
 export type EnvRegistry<S extends EnvSpecs> = { readonly [K in keyof S]: EnvValue<S[K]> } & {
   readonly $specs: S;
   readonly $keys: readonly string[];
+  /** Read only an explicitly supplied value, without the code default. */
+  readonly $readPresent: <K extends keyof S & string>(key: K) => z.output<S[K]["schema"]> | undefined;
 };
 
-const rawValue = (key: string, aliases: string[] = []): string | undefined => {
-  for (const name of [key, ...aliases]) {
+/** Effective value source; empty values fall through to the default or unset. */
+export type EnvSource = "env" | "alias" | "file" | "default" | "unset";
+
+type RawEnv = { value: string | undefined; source: "env" | "alias" | "file" | "unset" };
+
+// A mounted secret is a startup input, not a live configuration channel. A new
+// path is still observed when tests or tooling deliberately change process.env.
+const fileValues = new WeakMap<EnvSpec<unknown>, { path: string; value: string }>();
+
+const rawValue = (key: string, spec: EnvSpec<unknown>): RawEnv => {
+  const names = [key, ...(spec.aliases ?? [])];
+  const fileKey = `${key}_FILE`;
+  const path = spec.secretFile ? process.env[fileKey]?.trim() || undefined : undefined;
+  if (path !== undefined) {
+    const conflict = names.find((name) => process.env[name]?.trim());
+    if (conflict) throw new Error(`${conflict} and ${fileKey} must not both be set`);
+    const cached = fileValues.get(spec);
+    let value = cached?.path === path ? cached.value : undefined;
+    if (value === undefined) {
+      try {
+        value = readFileSync(path, "utf8");
+      } catch {
+        // File errors must identify the source without including contents or an underlying error.
+        throw new Error(`${fileKey} could not read file ${JSON.stringify(path)}`);
+      }
+      if (value.endsWith("\r\n")) value = value.slice(0, -2);
+      else if (value.endsWith("\n")) value = value.slice(0, -1);
+      fileValues.set(spec, { path, value });
+    }
+    return { value: value === "" ? undefined : value, source: value === "" ? "unset" : "file" };
+  }
+  for (const name of names) {
     const value = process.env[name]?.trim();
-    if (value) return value;
+    if (value) return { value, source: name === key ? "env" : "alias" };
   }
-  return undefined;
+  return { value: undefined, source: "unset" };
+};
+
+/** Inspect the effective source without evaluating defaults; invalid file configuration throws as on value access. */
+export const envSource = <S extends EnvSpecs>(registry: EnvRegistry<S>, key: keyof S & string): EnvSource => {
+  const spec = registry.$specs[key]!;
+  const { source } = rawValue(key, spec);
+  return source === "unset" && spec.default !== undefined ? "default" : source;
 };
 
 const isFactory = <T>(value: T | (() => T)): value is () => T => typeof value === "function";
 
 export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
-  const raw = rawValue(key, spec.aliases);
+  const { value: raw } = rawValue(key, spec);
   if (raw === undefined) {
     if (spec.default !== undefined) return isFactory(spec.default) ? spec.default() : spec.default;
     if (spec.required) throw new Error(`${key} is required`);
@@ -63,6 +106,7 @@ export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
   }
   const parsed = spec.schema.safeParse(raw);
   if (!parsed.success) {
+    if (spec.secretFile) throw new Error(`${key} is invalid`);
     const reason = parsed.error.issues.map((issue) => issue.message).join("; ") || "is invalid";
     throw new Error(`${key} ${reason}`);
   }
@@ -71,8 +115,19 @@ export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
 
 export const defineEnv = <S extends EnvSpecs>(specs: S): EnvRegistry<S> => {
   const keys = Object.freeze(Object.keys(specs));
-  const registry: Record<string, unknown> = { $specs: specs, $keys: keys };
+  const registry: Record<string, unknown> = {
+    $specs: specs,
+    $keys: keys,
+    $readPresent: (key: string) => {
+      const spec = specs[key];
+      if (!spec) throw new Error(`Unknown environment variable: ${key}`);
+      return readEnv(key, { ...spec, default: undefined, required: false });
+    },
+  };
   for (const key of keys) {
+    const spec = specs[key]!;
+    // Fail during module initialization, even when this secret is first used by a later request.
+    if (spec.secretFile && process.env[`${key}_FILE`]?.trim()) readEnv(key, spec);
     Object.defineProperty(registry, key, { enumerable: true, configurable: true, get: () => readEnv(key, specs[key]!) });
   }
   // The getters above are the only way to build a typed lazy object.

package/src/config/env.ts

@@ -4,23 +4,14 @@
  * `src/env.ts`; values are parsed lazily on access (see `define-env.ts`).
  */
 import { z } from "zod";
+import { DEFAULT_TRUSTED_PROXIES } from "../services/settings/validation";
 import { defineEnv, envBoolean, envList } from "./define-env";
+import { DEFAULT_WORKFLOW_AI_BUDGET, workflowAiBudgetSchema } from "./workflow-ai";
 
 const syncReplicas = z
   .enum(["1", "3", "5"], { error: "must be 1, 3, or 5" })
   .transform((value): 1 | 3 | 5 => (value === "1" ? 1 : value === "3" ? 3 : 5));
 
-const budgetSchema = z
-  .object({
-    maxStepsPerSource: z.number().int().positive(),
-    tasksPerMinute: z.number().int().positive(),
-    burst: z.number().int().positive(),
-    sourcesPer24Hours: z.number().int().positive(),
-    scopeConcurrent: z.number().int().positive(),
-    globalConcurrent: z.number().int().positive(),
-  })
-  .strict();
-
 const registry = defineEnv({
   // Process
   NODE_ENV: {
@@ -35,6 +26,7 @@ const registry = defineEnv({
   // Infrastructure
   DATABASE_URL: {
     schema: z.string(),
+    aliases: ["DATABASEURL", "TLS_DATABASE_URL", "POSTGRES_URL", "PGURL", "PG_URL", "TLS_POSTGRES_DATABASE_URL"],
     example: "postgresql://ipa:ipa@localhost:5432/ipa",
     doc: "Postgres connection read by Bun SQL and by application-owned pools.",
   },
@@ -54,7 +46,7 @@ const registry = defineEnv({
     schema: z.string(),
     default: "",
     example: "dev",
-    doc: "Sync namespace shared by every app of one installation; isolates its NATS resources from other installations on the same cluster.",
+    doc: "Sync namespace shared by every app of one installation; separates NATS resource names, not access. Use one NATS account per installation.",
   },
   SYNC_REPLICAS: {
     schema: syncReplicas,
@@ -88,9 +80,9 @@ const registry = defineEnv({
           return z.NEVER;
         }
       })
-      .pipe(budgetSchema),
-    default: { maxStepsPerSource: 2, tasksPerMinute: 10, burst: 20, sourcesPer24Hours: 2_000, scopeConcurrent: 1, globalConcurrent: 4 },
-    doc: "JSON scoped workflow inference budget: active or successful logical requests per source/24h, token-bucket admission per minute and burst, distinct sources per rolling 24h, outstanding tasks per scope and globally; capacity/rate overload uses bounded workflow retries, daily/source limits fail visibly, and cache hits consume no reservation.",
+      .pipe(workflowAiBudgetSchema),
+    default: DEFAULT_WORKFLOW_AI_BUDGET,
+    doc: "Deprecated: bootstraps `ai.workflow_budget` once when no stored value exists; remove after `cld admin settings status --env` succeeds. JSON scoped workflow inference budget: active or successful logical requests per source/24h, token-bucket admission per minute and burst, distinct sources per rolling 24h, outstanding tasks per scope and globally; capacity/rate overload uses bounded workflow retries, daily/source limits fail visibly, and cache hits consume no reservation.",
   },
 
   // Workflow inference: p95 ~4s in the pilot; 60s bounds a whole attempt,
@@ -98,12 +90,12 @@ const registry = defineEnv({
   WORKFLOW_AI_ATTEMPT_TIMEOUT_MS: {
     schema: z.coerce.number().int().positive(),
     default: 60_000,
-    doc: "Absolute workflow AI attempt budget in milliseconds, including admission and repair; expiry aborts the provider and follows the bounded retry policy.",
+    doc: "Deprecated: bootstraps `ai.workflow_attempt_timeout_ms` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Absolute workflow AI attempt budget in milliseconds, including admission and repair; expiry aborts the provider and follows the bounded retry policy.",
   },
   WORKFLOW_AI_QUEUE_TIMEOUT_MS: {
     schema: z.coerce.number().int().positive(),
     default: 60_000,
-    doc: "Maximum workflow AI queue wait in milliseconds; recovery fails overdue or lost deliveries visibly so an operator can retry the workflow.",
+    doc: "Deprecated: bootstraps `ai.workflow_queue_timeout_ms` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Maximum workflow AI queue wait in milliseconds; recovery fails overdue or lost deliveries visibly so an operator can retry the workflow.",
   },
 
   // Installation
@@ -115,12 +107,13 @@ const registry = defineEnv({
   GOTENBERG_URL: {
     schema: z.string(),
     example: "http://localhost:3001",
-    doc: "Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written.",
+    doc: "Deprecated: env only bootstraps `gotenberg.url`; remove after `cld admin settings status --env` succeeds. Internal Gotenberg base URL used to bootstrap the `gotenberg.url` PDF rendering setting; the stored setting wins once written.",
   },
   APP_SECRET: {
     schema: z.string(),
     default: "",
     scope: "secret",
+    secretFile: true,
     example: "change-me-generate-with-openssl-rand-hex-32",
     doc: "Deployment-wide secret for at-rest settings encryption and signed cursors; generate once with `openssl rand -hex 32` and never change it after data has been written.",
   },
@@ -128,37 +121,49 @@ const registry = defineEnv({
     schema: z.string(),
     default: "",
     scope: "secret",
+    secretFile: true,
     doc: "Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works.",
   },
 
+  // Gateway trust boundary
+  GATEWAY_TRUSTED_PROXIES: {
+    schema: envList,
+    default: DEFAULT_TRUSTED_PROXIES,
+    doc: "Deprecated: bootstraps `gateway.trusted_proxies` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Comma-separated IP addresses or CIDR ranges of the reverse proxies allowed to name the client in `X-Forwarded-For`; the default trusts loopback and private networks, which covers Traefik on a Docker network. Set the proxy's exact address or subnet when clients on private networks reach the gateway directly or through a proxy that appends to their `X-Forwarded-For`. Invalid bootstrap input with no stored row and invalid stored proxy lists stop gateway startup.",
+  },
+
   // Outbound network
   OUTGOING_MAIL_ALLOWED_TARGETS: {
     schema: envList,
     default: [],
     scope: "runtime",
-    doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
+    doc: "Deprecated: bootstraps `outgoing_mail.allowed_targets` once when no stored value exists; remove after `cld admin settings status --env` succeeds. Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` are ignored with a bootstrap warning.",
   },
 
   // Identity and OAuth
   CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     example: "change-me-generate-with-openssl-rand-hex-32",
     doc: "Core only: 64-hex KEK for platform identity signing keys stored in Postgres; generate once with `openssl rand -hex 32` and never distribute it to other apps.",
   },
   CLOUD_IDENTITY_NEXT_KEY: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     doc: "Core only: pre-distributed next KEK before promoting it to current; cannot be combined with `CLOUD_IDENTITY_PREVIOUS_KEY`.",
   },
   CLOUD_IDENTITY_PREVIOUS_KEY: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     doc: "Core only: old KEK set during an explicit rolling rewrap of stored identity signing keys, then removed.",
   },
   CLOUD_OAUTH_BROKER_SECRET: {
     schema: z.string(),
     scope: "secret",
+    secretFile: true,
     doc: "Core and OAuth only: 64-hex secret that lets the OAuth app request token signatures from Core; generate independently with `openssl rand -hex 32`.",
   },
   CLOUD_CORE_INTERNAL_ORIGIN: {
@@ -168,11 +173,12 @@ const registry = defineEnv({
   CLOUD_APP_CREDENTIAL: {
     schema: z.string(),
     scope: "secret",
-    doc: "App-bound workload credential provisioned through Core's admin workload API; background apps such as Mail need one with `identity:invoke`.",
+    secretFile: true,
+    doc: "Optional host-run app override for the automatically delivered app workload credential; provision through Core's admin workload API with `identity:invoke`.",
   },
   CLOUD_IDENTITY_JWKS_ORIGIN: {
     schema: z.string(),
-    doc: "Optional private origin of the Core listener for session and invocation JWKS; unset fetches keys from the public issuer origin.",
+    doc: "Deprecated: use `CLOUD_CORE_INTERNAL_ORIGIN`; the explicit old origin remains honored for this release. Optional private origin of the Core listener for session and invocation JWKS; unset uses `CLOUD_CORE_INTERNAL_ORIGIN`, then the public issuer origin.",
   },
   CLOUD_OAUTH_JWKS_ORIGIN: {
     schema: z.string(),

package/src/config/index.ts

@@ -4,5 +4,16 @@
  * by application `src/env.ts` files. SSR config is per-app via defineApp().
  */
 
-export { defineEnv, type EnvRegistry, type EnvScope, type EnvSpec, type EnvSpecs, envBoolean, envList, envString } from "./define-env";
+export {
+  defineEnv,
+  type EnvRegistry,
+  type EnvScope,
+  type EnvSource,
+  type EnvSpec,
+  type EnvSpecs,
+  envBoolean,
+  envList,
+  envSource,
+  envString,
+} from "./define-env";
 export { env } from "./env";

package/src/config/workflow-ai.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const workflowAiBudgetSchema = z
+  .object({
+    maxStepsPerSource: z.number().int().positive(),
+    tasksPerMinute: z.number().int().positive(),
+    burst: z.number().int().positive(),
+    sourcesPer24Hours: z.number().int().positive(),
+    scopeConcurrent: z.number().int().positive(),
+    globalConcurrent: z.number().int().positive(),
+  })
+  .strict();
+export const DEFAULT_WORKFLOW_AI_BUDGET = {
+  maxStepsPerSource: 2,
+  tasksPerMinute: 10,
+  burst: 20,
+  sourcesPer24Hours: 2_000,
+  scopeConcurrent: 1,
+  globalConcurrent: 4,
+};
+export const validateWorkflowAiBudget = (value: unknown): string | undefined => {
+  try {
+    if (typeof value === "string" && workflowAiBudgetSchema.safeParse(JSON.parse(value)).success) return;
+  } catch {
+    /* invalid JSON */
+  }
+  return "Workflow AI budget must be a JSON object with positive whole numbers for maxStepsPerSource, tasksPerMinute, burst, sourcesPer24Hours, scopeConcurrent and globalConcurrent, without extra fields";
+};

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;
+};