@k2b/cloud 0.40.0 → 0.42.0

package/src/contracts/app.ts

@@ -1,4 +1,5 @@
 import type { Sync } from "@k2b/sync";
+import type { AppAccessRule } from "./app-access";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
@@ -15,7 +16,7 @@ export type LegalLink = {
   icon?: string;
 };
 
-/** Static page links for the global search UI, ranked after resource results.
+/** Static page links for the global search UI, shown before resource results.
  * These declare navigation only; they do not create capabilities or readers.
  */
 export type AppSearchLink = {
@@ -24,6 +25,7 @@ export type AppSearchLink = {
   description?: string;
   href: string;
   icon?: string;
+  /** Alternate search terms. At `nav.href`, these also match the automatic app launcher. */
   keywords?: readonly string[];
 };
 
@@ -121,6 +123,7 @@ export type AppPanel = {
 };
 
 export type AppMeta = {
+  access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;

package/src/contracts/approvals.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { APP_APPROVAL_LIMITS } from "./app-approval";
-import { CapabilityActionReviewDataSchema, CapabilityAppIdSchema } from "./capabilities";
+import { CapabilityActionReviewPresentationSchema, CapabilityAppIdSchema } from "./capabilities";
 
 export { APPROVAL_COUNTS_PATH, APPROVALS_API_PATH, APPROVALS_PAGE_PATH } from "./approval-paths";
 
@@ -42,7 +42,7 @@ export const PendingApprovalSchema = z
     /** What the person reads: the first line names the app and the Action, later lines add `Label: value` details. */
     sentence: z.string(),
     /** The owning app's review as the person saw it when Cloud asked. */
-    review: CapabilityActionReviewDataSchema.nullable(),
+    review: CapabilityActionReviewPresentationSchema.nullable(),
     /** Where the request waits. The title is chat content, written by a person or a model, never Cloud's own words. */
     requester: z.object({ kind: z.literal("chat"), appId: z.string(), title: z.string().nullable(), href: z.string() }).strict(),
     /** Ways the person may remember this approval, the same the chat card offers. */

package/src/contracts/avatar.ts

@@ -0,0 +1,186 @@
+import { z } from "zod";
+
+/**
+ * The shape set of built avatars: a person's comic avatar and an agent's robot. A stored config names one option per
+ * part by a stable id. Ids are never removed or renamed once released, so every stored config keeps rendering; new
+ * options only add ids. `v` changes only when the schema itself breaks, and each version keeps its own schema and
+ * drawing.
+ */
+export const AVATAR_SHAPE_SET_VERSION = 1;
+
+export const PERSON_FACES = ["round", "oval", "square"] as const;
+export const PERSON_SKIN_TONES = ["s1", "s2", "s3", "s4", "s5", "s6"] as const;
+/** Every hairstyle passed a human review for unwanted associations; see the review list in the renderer tests. */
+export const PERSON_HAIRSTYLES = ["none", "short", "buzz", "curly", "afro", "long", "bob", "bun", "locs"] as const;
+export const PERSON_HAIR_COLORS = ["black", "dark", "brown", "blond", "red", "grey", "white", "blue", "pink"] as const;
+export const PERSON_EYES = ["dots", "ovals", "happy", "wink", "calm"] as const;
+export const PERSON_BROWS = ["none", "straight", "arched", "thick", "raised"] as const;
+export const PERSON_MOUTHS = ["smile", "grin", "neutral", "oh", "smirk"] as const;
+export const PERSON_BEARDS = ["none", "stubble", "moustache", "goatee", "full"] as const;
+export const PERSON_GLASSES = ["none", "round", "square", "half", "sun"] as const;
+export const PERSON_HEADWEAR = ["none", "beanie", "cap", "hijab", "turban", "kippa", "phones"] as const;
+export const PERSON_EXTRAS = ["none", "freckles", "blush", "earrings", "mole"] as const;
+export const AVATAR_BACKGROUNDS = ["sky", "mint", "sand", "rose", "lilac", "stone", "peach", "teal"] as const;
+
+export const ROBOT_HEADS = ["square", "round", "capsule", "tv"] as const;
+export const ROBOT_ANTENNAS = ["none", "ball", "double", "dish"] as const;
+export const ROBOT_EYES = ["round", "visor", "pixel", "cyclops", "happy"] as const;
+export const ROBOT_MOUTHS = ["grill", "smile", "led", "line", "none"] as const;
+export const ROBOT_BODIES = ["plain", "panel", "light", "buttons"] as const;
+export const ROBOT_COLORS = ["steel", "white", "blue", "teal", "coral", "yellow", "purple", "graphite"] as const;
+
+export const PersonAvatarSchema = z
+  .object({
+    v: z.literal(AVATAR_SHAPE_SET_VERSION),
+    kind: z.literal("person"),
+    face: z.enum(PERSON_FACES),
+    skin: z.enum(PERSON_SKIN_TONES),
+    hair: z.enum(PERSON_HAIRSTYLES),
+    hairColor: z.enum(PERSON_HAIR_COLORS),
+    eyes: z.enum(PERSON_EYES),
+    brows: z.enum(PERSON_BROWS),
+    mouth: z.enum(PERSON_MOUTHS),
+    beard: z.enum(PERSON_BEARDS),
+    glasses: z.enum(PERSON_GLASSES),
+    head: z.enum(PERSON_HEADWEAR),
+    extra: z.enum(PERSON_EXTRAS),
+    bg: z.enum(AVATAR_BACKGROUNDS),
+  })
+  .strict();
+export type PersonAvatar = z.infer<typeof PersonAvatarSchema>;
+
+export const RobotAvatarSchema = z
+  .object({
+    v: z.literal(AVATAR_SHAPE_SET_VERSION),
+    kind: z.literal("robot"),
+    head: z.enum(ROBOT_HEADS),
+    antenna: z.enum(ROBOT_ANTENNAS),
+    eyes: z.enum(ROBOT_EYES),
+    mouth: z.enum(ROBOT_MOUTHS),
+    body: z.enum(ROBOT_BODIES),
+    color: z.enum(ROBOT_COLORS),
+    bg: z.enum(AVATAR_BACKGROUNDS),
+  })
+  .strict();
+export type RobotAvatar = z.infer<typeof RobotAvatarSchema>;
+
+export const AvatarConfigSchema = z.discriminatedUnion("kind", [PersonAvatarSchema, RobotAvatarSchema]);
+export type AvatarConfig = z.infer<typeof AvatarConfigSchema>;
+
+/** Which picture others see: an uploaded photo, the built avatar, or the fallback (initials for people). */
+export const AVATAR_KINDS = ["photo", "built", "initials"] as const;
+export type AvatarKind = (typeof AVATAR_KINDS)[number];
+
+/** A stored config is a handful of short ids; anything larger than this is not a config. */
+export const MAX_AVATAR_CONFIG_BYTES = 1024;
+
+/** The JSON text whose hash identifies a built avatar: keys in schema order, so equal configs hash equally. */
+export const canonicalAvatarConfig = (config: AvatarConfig): string =>
+  JSON.stringify(config.kind === "person" ? PersonAvatarSchema.parse(config) : RobotAvatarSchema.parse(config));
+
+type Random = () => number;
+
+const pick = <T>(list: readonly T[], random: Random): T => list[Math.floor(random() * list.length) % list.length] as T;
+
+/** A first draft for a person: random, with a calm smile and nothing on top, so the person starts from a plain face. */
+export const startPersonAvatar = (random: Random = Math.random): PersonAvatar => ({
+  v: AVATAR_SHAPE_SET_VERSION,
+  kind: "person",
+  face: pick(PERSON_FACES, random),
+  skin: pick(PERSON_SKIN_TONES, random),
+  hair: pick(PERSON_HAIRSTYLES.slice(1), random),
+  hairColor: pick(PERSON_HAIR_COLORS.slice(0, 6), random),
+  eyes: pick(PERSON_EYES, random),
+  brows: pick(PERSON_BROWS.slice(1), random),
+  mouth: "smile",
+  beard: "none",
+  glasses: "none",
+  head: "none",
+  extra: "none",
+  bg: pick(AVATAR_BACKGROUNDS, random),
+});
+
+/** Headwear the random button may choose; religious headwear is only ever the person's own choice. */
+export const RANDOM_PERSON_HEADWEAR = ["beanie", "cap", "phones"] as const;
+
+/** "Random" in the builder: everything changes except the skin tone, which stays the person's choice. */
+export const randomizePersonAvatar = (current: PersonAvatar, random: Random = Math.random): PersonAvatar => {
+  const maybe = <T extends string>(chance: number, list: readonly T[]): T | "none" => (random() < chance ? pick(list, random) : "none");
+  return {
+    v: AVATAR_SHAPE_SET_VERSION,
+    kind: "person",
+    face: pick(PERSON_FACES, random),
+    skin: current.skin,
+    hair: pick(PERSON_HAIRSTYLES.slice(1), random),
+    hairColor: random() < 0.85 ? pick(PERSON_HAIR_COLORS.slice(0, 7), random) : pick(PERSON_HAIR_COLORS, random),
+    eyes: pick(PERSON_EYES, random),
+    brows: pick(PERSON_BROWS.slice(1), random),
+    mouth: pick(PERSON_MOUTHS, random),
+    beard: maybe(0.3, PERSON_BEARDS.slice(1)),
+    glasses: maybe(0.35, PERSON_GLASSES.slice(1)),
+    head: maybe(0.25, RANDOM_PERSON_HEADWEAR),
+    extra: maybe(0.35, PERSON_EXTRAS.slice(1)),
+    bg: pick(AVATAR_BACKGROUNDS, random),
+  };
+};
+
+export const randomRobotAvatar = (random: Random = Math.random): RobotAvatar => ({
+  v: AVATAR_SHAPE_SET_VERSION,
+  kind: "robot",
+  head: pick(ROBOT_HEADS, random),
+  antenna: pick(ROBOT_ANTENNAS, random),
+  eyes: pick(ROBOT_EYES, random),
+  mouth: pick(ROBOT_MOUTHS, random),
+  body: pick(ROBOT_BODIES, random),
+  color: pick(ROBOT_COLORS, random),
+  bg: pick(AVATAR_BACKGROUNDS, random),
+});
+
+/** A small seeded generator (cyrb53 seed, mulberry32 stream): the same seed draws the same robot everywhere. */
+export const seededRandom = (seed: string): Random => {
+  let h1 = 0xdeadbeef;
+  let h2 = 0x41c6ce57;
+  for (let index = 0; index < seed.length; index++) {
+    const code = seed.charCodeAt(index);
+    h1 = Math.imul(h1 ^ code, 2654435761);
+    h2 = Math.imul(h2 ^ code, 1597334677);
+  }
+  let state = (Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909)) >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+/**
+ * The parts a seed draws from, frozen at shape set 1. New robot options join the builder, never this list, so an
+ * agent's robot never changes when the shape set grows.
+ */
+const ROBOT_SEED_PARTS_V1 = {
+  head: ["square", "round", "capsule", "tv"],
+  antenna: ["none", "ball", "double", "dish"],
+  eyes: ["round", "visor", "pixel", "cyclops", "happy"],
+  mouth: ["grill", "smile", "led", "line", "none"],
+  body: ["plain", "panel", "light", "buttons"],
+  color: ["steel", "white", "blue", "teal", "coral", "yellow", "purple", "graphite"],
+  bg: ["sky", "mint", "sand", "rose", "lilac", "stone", "peach", "teal"],
+} as const satisfies { [Part in Exclude<keyof RobotAvatar, "v" | "kind">]: readonly RobotAvatar[Part][] };
+
+/** The robot an agent shows until someone changes it: drawn from its account id, so it never changes by itself. */
+export const robotAvatarFromSeed = (seed: string): RobotAvatar => {
+  const random = seededRandom(seed);
+  return {
+    v: AVATAR_SHAPE_SET_VERSION,
+    kind: "robot",
+    head: pick(ROBOT_SEED_PARTS_V1.head, random),
+    antenna: pick(ROBOT_SEED_PARTS_V1.antenna, random),
+    eyes: pick(ROBOT_SEED_PARTS_V1.eyes, random),
+    mouth: pick(ROBOT_SEED_PARTS_V1.mouth, random),
+    body: pick(ROBOT_SEED_PARTS_V1.body, random),
+    color: pick(ROBOT_SEED_PARTS_V1.color, random),
+    bg: pick(ROBOT_SEED_PARTS_V1.bg, random),
+  };
+};

package/src/contracts/capabilities.ts

@@ -8,6 +8,7 @@ import {
 export * from "./capability-streams";
 
 import { z } from "zod";
+import type { RequestAuthority } from "../server/middleware/auth";
 import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";
 
@@ -177,6 +178,9 @@ export type CapabilityReach = (typeof CAPABILITY_REACHES)[number];
 export const CAPABILITY_ACTION_OUTCOMES = ["running", "done", "rejected", "not_run", "unknown"] as const;
 export type CapabilityActionOutcome = (typeof CAPABILITY_ACTION_OUTCOMES)[number];
 export const CAPABILITY_MAX_REVIEW_BYTES = 32 * 1024;
+/** Full review text and metadata, separate from the compact card and ordinary capability results. */
+export const CAPABILITY_MAX_REVIEW_CONTENT_BYTES = 16 * 1024 * 1024;
+export const CAPABILITY_MAX_REVIEW_RESPONSE_BYTES = CAPABILITY_MAX_REVIEW_CONTENT_BYTES + CAPABILITY_MAX_REVIEW_BYTES + 11;
 export const CapabilityActionPolicySchema = z.union([
   z.object({ silent: z.enum(CAPABILITY_REACHES), routines: z.literal(false).optional() }).strict(),
   z.object({ ask: z.enum(CAPABILITY_ASK_REASONS) }).strict(),
@@ -188,14 +192,14 @@ const reviewLine = (max: number, min = 1) =>
     .string()
     .min(min)
     .max(max)
-    .refine((text) => !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(text), "Contains unsafe characters");
+    .refine((text) => !/[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u.test(text), "Contains unsafe characters");
 const reviewBlock = (max: number) =>
   z
     .string()
     .max(max)
-    .refine((text) => !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(text.replace(/[\n\t]/g, "")), "Contains unsafe characters");
+    .refine((text) => !/[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u.test(text.replace(/[\n\t]/g, "")), "Contains unsafe characters");
 export const CapabilityPersonSchema = z
-  .object({ name: reviewLine(120).optional(), address: reviewLine(320).optional(), userId: z.uuid().optional() })
+  .object({ name: reviewLine(200).optional(), address: reviewLine(320).optional(), userId: z.uuid().optional() })
   .strict()
   .refine((person) => person.name !== undefined || person.address !== undefined, "A person needs a name or address");
 export type CapabilityPerson = z.infer<typeof CapabilityPersonSchema>;
@@ -432,60 +436,143 @@ export const CapabilityPreviewSchema = z.discriminatedUnion("kind", [
     .strict(),
 ]);
 export type CapabilityPreview = z.infer<typeof CapabilityPreviewSchema>;
-export const CapabilityActionCallReviewSchema = z
-  .object({
-    locale: z.string(),
-    sentence: z
-      .object({
-        action: reviewTemplate,
-        running: reviewTemplate,
-        done: reviewTemplate,
-        confirm: reviewTemplate,
-        decline: reviewTemplate,
-        rejected: reviewTemplate.optional(),
-        notRun: reviewTemplate.optional(),
-        short: reviewTemplate.refine((text) => text.length <= 60, "short exceeds 60 characters").optional(),
-      })
-      .strict(),
-    slots: reviewSlots.readonly(),
-    preview: CapabilityPreviewSchema.optional(),
-    consequences: z.array(CapabilityConsequenceSchema).max(6).optional(),
-    ask: z.enum(CAPABILITY_ASK_REASONS).optional(),
-    reach: z.enum(CAPABILITY_REACHES).optional(),
-    effects: z.number().int().min(1).max(1000).optional(),
-    check: z
-      .object({ query: CapabilityLocalIdSchema, input: z.record(z.string(), z.unknown()) })
-      .strict()
-      .optional(),
-    scope: z.string().min(1).max(200).optional(),
-    links: z.array(CapabilitySemanticLinkSchema).max(10).optional(),
-  })
-  .strict()
-  .superRefine((review, ctx) => {
-    for (const [form, text] of Object.entries(review.sentence)) {
-      if (text === undefined) continue;
-      const complete = form === "action" || form === "running" || form === "done";
-      for (const message of capabilitySentenceIssues(text, review.slots, complete, form === "action"))
-        ctx.addIssue({ code: "custom", path: ["sentence", form], message });
-      if ((form === "confirm" || form === "decline") && [...text.matchAll(/\{[a-z][A-Za-z0-9]{0,31}\}/g)].length > 1)
-        ctx.addIssue({ code: "custom", path: ["sentence", form], message: "Buttons name at most one slot" });
-    }
-  });
+/** Complete passive content; no attachment bytes, HTML, omitted entries, or silently shortened strings. */
+// Construct complete review validators in pure calls: unrelated browser consumers of resource refs do not need them.
+export const CapabilityReviewContentSchema = /* @__PURE__ */ (() => {
+  const fullReviewPerson = z
+    .object({
+      name: z.string().max(200).optional(),
+      address: z.string().max(320).optional(),
+      userId: z.uuid().optional(),
+    })
+    .strict()
+    .refine((person) => person.name !== undefined || person.address !== undefined, "A person needs a name or address");
+  return z
+    .discriminatedUnion("kind", [
+      z
+        .object({
+          kind: z.literal("message"),
+          baseRevision: z.number().int().nonnegative().optional(),
+          from: fullReviewPerson.optional(),
+          to: z.array(fullReviewPerson).max(600),
+          cc: z.array(fullReviewPerson).max(600).optional(),
+          bcc: z.array(fullReviewPerson).max(600).optional(),
+          subject: z.string().max(998),
+          body: z.string().max(CAPABILITY_MAX_REVIEW_CONTENT_BYTES),
+          format: z.literal("plain"),
+          attachments: z
+            .array(
+              z
+                .object({
+                  name: z.string().min(1).max(255),
+                  size: z.number().int().nonnegative().optional(),
+                  ref: CloudResourceRefSchema.optional(),
+                })
+                .strict(),
+            )
+            .max(202)
+            .optional(),
+          sendAt: reviewTime.optional(),
+          warnings: z.array(z.string().max(300)).max(6).optional(),
+        })
+        .strict(),
+      z
+        .object({
+          kind: z.literal("page"),
+          baseRevision: z.number().int().nonnegative().optional(),
+          title: z.string().max(200),
+          place: z.string().max(200).optional(),
+          body: z.string().max(CAPABILITY_MAX_REVIEW_CONTENT_BYTES),
+          format: z.literal("plain"),
+        })
+        .strict(),
+    ])
+    .superRefine((content, ctx) => {
+      if (content.kind === "message" && content.to.length + (content.cc?.length ?? 0) + (content.bcc?.length ?? 0) > 600)
+        ctx.addIssue({ code: "custom", message: "Full review content exceeds 600 recipients" });
+      if (new TextEncoder().encode(JSON.stringify(content)).byteLength > CAPABILITY_MAX_REVIEW_CONTENT_BYTES)
+        ctx.addIssue({ code: "custom", message: "Full review content exceeds 16 MiB" });
+    });
+})();
+export type CapabilityReviewContent = z.infer<typeof CapabilityReviewContentSchema>;
+/** Cloud supplies this after storing a review. It is a locator, never an authorization token. */
+export const CapabilityReviewContentRefSchema = /* @__PURE__ */ (() =>
+  z
+    .object({
+      href: z
+        .string()
+        .regex(
+          /^\/api\/approvals\/(?:[a-fA-F0-9-]{36}\/content|conversations\/[a-fA-F0-9-]{36}\/turns\/[a-fA-F0-9-]{36}\/reviews\/(?!\.{1,2}$)(?:[A-Za-z0-9_!~*'().-]|%[A-Fa-f0-9]{2})+)$/,
+        )
+        .max(2048),
+      digest: z.string().regex(/^[a-f0-9]{64}$/),
+    })
+    .strict())();
+export type CapabilityReviewContentRef = z.infer<typeof CapabilityReviewContentRefSchema>;
+export const CapabilityActionCallReviewSchema = /* @__PURE__ */ (() =>
+  z
+    .object({
+      locale: z.string(),
+      sentence: z
+        .object({
+          action: reviewTemplate,
+          running: reviewTemplate,
+          done: reviewTemplate,
+          confirm: reviewTemplate,
+          decline: reviewTemplate,
+          rejected: reviewTemplate.optional(),
+          notRun: reviewTemplate.optional(),
+          short: reviewTemplate.refine((text) => text.length <= 60, "short exceeds 60 characters").optional(),
+        })
+        .strict(),
+      slots: reviewSlots.readonly(),
+      preview: CapabilityPreviewSchema.optional(),
+      content: CapabilityReviewContentSchema.optional(),
+      consequences: z.array(CapabilityConsequenceSchema).max(6).optional(),
+      ask: z.enum(CAPABILITY_ASK_REASONS).optional(),
+      reach: z.enum(CAPABILITY_REACHES).optional(),
+      effects: z.number().int().min(1).max(1000).optional(),
+      check: z
+        .object({ query: CapabilityLocalIdSchema, input: z.record(z.string(), z.unknown()) })
+        .strict()
+        .optional(),
+      scope: z.string().min(1).max(200).optional(),
+      links: z.array(CapabilitySemanticLinkSchema).max(10).optional(),
+    })
+    .strict()
+    .superRefine((review, ctx) => {
+      for (const [form, text] of Object.entries(review.sentence)) {
+        if (text === undefined) continue;
+        const complete = form === "action" || form === "running" || form === "done";
+        for (const message of capabilitySentenceIssues(text, review.slots, complete, form === "action"))
+          ctx.addIssue({ code: "custom", path: ["sentence", form], message });
+        if ((form === "confirm" || form === "decline") && [...text.matchAll(/\{[a-z][A-Za-z0-9]{0,31}\}/g)].length > 1)
+          ctx.addIssue({ code: "custom", path: ["sentence", form], message: "Buttons name at most one slot" });
+      }
+    }))();
 export type CapabilityActionCallReview = z.infer<typeof CapabilityActionCallReviewSchema>;
 export type CapabilityActionReviewData = CapabilityActionCallReview | CapabilityActionReview;
-export const CapabilityActionReviewDataSchema = z
-  .unknown()
-  .transform((value, ctx) => {
-    const schema =
-      value !== null && typeof value === "object" && Object.hasOwn(value, "sentence")
-        ? CapabilityActionCallReviewSchema
-        : CapabilityActionReviewSchema;
-    const parsed = schema.safeParse(value);
-    if (parsed.success) return parsed.data;
-    for (const issue of parsed.error.issues) ctx.addIssue({ code: "custom", path: issue.path, message: issue.message });
-    return z.NEVER;
-  })
-  .pipe(z.union([CapabilityActionCallReviewSchema, CapabilityActionReviewSchema]));
+export const CapabilityActionReviewDataSchema = /* @__PURE__ */ (() =>
+  z
+    .unknown()
+    .transform((value, ctx) => {
+      const schema =
+        value !== null && typeof value === "object" && Object.hasOwn(value, "sentence")
+          ? CapabilityActionCallReviewSchema
+          : CapabilityActionReviewSchema;
+      const parsed = schema.safeParse(value);
+      if (parsed.success) return parsed.data;
+      for (const issue of parsed.error.issues) ctx.addIssue({ code: "custom", path: issue.path, message: issue.message });
+      return z.NEVER;
+    })
+    .pipe(z.union([CapabilityActionCallReviewSchema, CapabilityActionReviewSchema])))();
+/** Compact Cloud presentation. Providers return the strict review above, never a client-supplied content locator. */
+export const CapabilityActionReviewPresentationSchema = /* @__PURE__ */ (() =>
+  z.union([
+    CapabilityActionCallReviewSchema.safeExtend({ contentRef: CapabilityReviewContentRefSchema.optional() }),
+    CapabilityActionReviewSchema,
+  ]))();
+export type CapabilityActionReviewPresentation = z.infer<typeof CapabilityActionReviewPresentationSchema>;
 export const CapabilityActionReceiptSchema = z
   .object({ ...sentenceShape, preview: CapabilityPreviewSchema.optional() })
   .strict()
@@ -676,6 +763,12 @@ export const UniversalSearchDataSchema = z.array(CloudResourceViewSchema).max(10
 export type UniversalSearchData = z.infer<typeof UniversalSearchDataSchema>;
 
 export type CapabilityExecutionContext = {
+  /**
+   * Resolved request authority, supplied by the framework for execution, review
+   * and streams. Optional for existing in-process callers; authority-aware
+   * services fail closed when it is absent. Preserve its credential limits.
+   */
+  authority?: RequestAuthority;
   actor: RequestActor;
   accessSubject: AccessSubject;
   user: User | null;
@@ -695,6 +788,7 @@ export type CapabilityExecutionContext = {
   requestId: string;
   /** Cloud surface that invoked this capability. */
   origin: CapabilityOrigin;
+  /** Caller cancellation or shared dispatch deadline; forward it to expensive work. */
   signal: AbortSignal;
 };
 

package/src/contracts/geo-admin.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+
+/** Geoapify plans in the order the administration offers them. */
+export const GEO_PLAN_IDS = ["free", "api10", "api25", "api50", "api100", "api250", "custom"] as const;
+export type GeoPlanId = (typeof GEO_PLAN_IDS)[number];
+
+/**
+ * Ledger function groups in display order. Every paid geo call reserves under one of these groups;
+ * the administration shows one share line per group.
+ */
+export const GEO_USAGE_GROUPS = ["tiles", "places", "route", "address"] as const;
+export type GeoUsageGroup = (typeof GEO_USAGE_GROUPS)[number];
+
+/** Largest credit value a geo budget setting accepts (stored as thousandths in a bigint ledger). */
+export const GEO_MAX_CREDITS = Math.floor(Number.MAX_SAFE_INTEGER / 1000);
+/** Largest custom request rate the token bucket accepts. */
+export const GEO_MAX_RPS = Math.floor(Number.MAX_SAFE_INTEGER / 9000);
+/** Upper bound of a pasted provider key; Geoapify keys are 32 characters. */
+export const GEO_MAX_KEY_LENGTH = 256;
+
+export type GeoAdminPerson = { id: string; name: string };
+
+export type GeoAdminKey = {
+  /** `unreadable`: a stored key exists but this installation cannot decrypt it; geo is off until it is replaced or removed. */
+  state: "none" | "set" | "unreadable";
+  setAt: string | null;
+  setBy: GeoAdminPerson | null;
+};
+
+export type GeoAdminBudget = {
+  plan: GeoPlanId;
+  customRps: number;
+  customDailyCredits: number;
+  monthlyCredits: number;
+  personDailyCredits: number;
+  /** Budget settings whose stored value cannot be read; saving the form replaces them. */
+  unreadable: Array<GeoBudgetField | "plan">;
+  changedAt: string | null;
+  changedBy: GeoAdminPerson | null;
+};
+
+export type GeoAdminStatus = {
+  key: GeoAdminKey;
+  budget: GeoAdminBudget;
+  plans: Record<Exclude<GeoPlanId, "custom">, { dailyCredits: number; rps: number }>;
+  /** `app.timezone`: dates on the page and the budget periods use it. */
+  timezone: string;
+};
+
+export type GeoAdminUsage = {
+  /** Credits. Values may carry fractions (a map tile costs 0.25). */
+  month: { period: string; used: number; limit: number; resetsAt: string };
+  /** Cloud-wide use today against the provider's daily allowance of the selected plan. */
+  today: { period: string; used: number; allowance: number; resetsAt: string };
+  shares: Array<{ group: GeoUsageGroup; credits: number }>;
+  /** Access subjects whose use today reached the per-person daily limit. */
+  peopleAtLimit: number;
+  timezone: string;
+};
+
+export const GeoKeyInputSchema = z.object({ apiKey: z.string().max(GEO_MAX_KEY_LENGTH * 4) }).strict();
+
+export const GeoBudgetInputSchema = z
+  .object({
+    plan: z.enum(GEO_PLAN_IDS),
+    customRps: z.unknown(),
+    customDailyCredits: z.unknown(),
+    monthlyCredits: z.unknown(),
+    personDailyCredits: z.unknown(),
+  })
+  .strict();
+export type GeoBudgetInput = z.infer<typeof GeoBudgetInputSchema>;
+export type GeoBudgetField = "customRps" | "customDailyCredits" | "monthlyCredits" | "personDailyCredits";
+
+/** Stable field error codes; the page renders their text. */
+export const GeoBudgetFieldErrorSchema = z.discriminatedUnion("code", [
+  z.object({ code: z.literal("not_whole_number") }),
+  z.object({ code: z.literal("too_small"), min: z.number() }),
+  z.object({ code: z.literal("too_large"), max: z.number() }),
+  z.object({ code: z.literal("above_monthly"), max: z.number() }),
+]);
+export type GeoBudgetFieldError = z.infer<typeof GeoBudgetFieldErrorSchema>;
+/** The 400 answer of a refused budget save. */
+export const GeoBudgetRefusalSchema = z.object({
+  code: z.literal("geo_budget_invalid"),
+  errors: z.partialRecord(z.enum(["customRps", "customDailyCredits", "monthlyCredits", "personDailyCredits"]), GeoBudgetFieldErrorSchema),
+});
+
+export type GeoKeyError =
+  | { code: "geo_key_missing" }
+  | { code: "geo_key_malformed" }
+  | { code: "geo_key_rejected" }
+  | { code: "geo_key_unverified" };
+
+/** Validate one budget number; `null` when it is acceptable. */
+const checkNumber = (value: unknown, min: number, max: number): GeoBudgetFieldError | null => {
+  if (typeof value !== "number" || !Number.isInteger(value)) return { code: "not_whole_number" };
+  if (value < min) return { code: "too_small", min };
+  if (value > max) return { code: "too_large", max };
+  return null;
+};
+
+/** Check the whole form before anything is written; the same rules as the settings registry plus the pair rule. */
+export const validateGeoBudget = (input: GeoBudgetInput) => {
+  const errors: Partial<Record<GeoBudgetField, GeoBudgetFieldError>> = {};
+  const fields: Array<[GeoBudgetField, number, number]> = [
+    ["monthlyCredits", 0, GEO_MAX_CREDITS],
+    ["personDailyCredits", 0, GEO_MAX_CREDITS],
+  ];
+  if (input.plan === "custom") fields.push(["customRps", 1, GEO_MAX_RPS], ["customDailyCredits", 1, GEO_MAX_CREDITS]);
+  for (const [field, min, max] of fields) {
+    const error = checkNumber(input[field], min, max);
+    if (error) errors[field] = error;
+  }
+  const month = input.monthlyCredits,
+    day = input.personDailyCredits;
+  if (!errors.monthlyCredits && !errors.personDailyCredits && typeof month === "number" && typeof day === "number" && day > month)
+    errors.personDailyCredits = { code: "above_monthly", max: month };
+  return errors;
+};
+
+/** Shape check before the provider sees a key: printable ASCII without spaces, as Geoapify issues them. */
+export const geoKeyProblem = (apiKey: string): "geo_key_missing" | "geo_key_malformed" | null => {
+  if (!apiKey) return "geo_key_missing";
+  if (apiKey.length > GEO_MAX_KEY_LENGTH || !/^[\x21-\x7e]+$/.test(apiKey)) return "geo_key_malformed";
+  return null;
+};

package/src/contracts/geo-map.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const GeoMapStyleInputSchema = z
+  .object({
+    theme: z.enum(["light", "dark"]).default("light").describe("Map appearance; labels use the request locale."),
+  })
+  .strict();
+export const GeoMapStyleDataSchema = z
+  .object({
+    styleUrl: z.string().startsWith("/api/geo/style?"),
+    attribution: z.array(z.object({ label: z.string(), href: z.url() }).strict()),
+  })
+  .strict();
+export const geoMapContract = { style: { id: "map.style", input: GeoMapStyleInputSchema, data: GeoMapStyleDataSchema } } as const;
+
+// This is a transport memory budget, not an asserted provider maximum. At Free's
+// 20 tile requests/s and 10 s deadline, buffered tile bodies occupy at most 200 MiB.
+export const GEO_MAX_TILE_BYTES = 1024 * 1024;
+export const GEO_MAP_MAX_ZOOM = 14;