@k2b/cloud 0.44.0 → 0.46.0

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

package/src/contracts/geo-snapshot.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+// Matches the geo result JSON envelope and the existing print decoder budgets.
+export const GEO_SNAPSHOT_MAX_METADATA_BYTES = 256 * 1024;
+export const GEO_SNAPSHOT_MAX_PIXELS = 16 * 1024 * 1024;
+export const GEO_SNAPSHOT_MAX_BYTES = 32 * 1024 * 1024;
+export const GeoMapSnapshotIdSchema = z
+  .string()
+  .min(1)
+  .max(100)
+  .regex(/^[A-Za-z0-9_-]+$/);
+export const GeoMapSnapshotImageSchema = z
+  .strictObject({
+    id: GeoMapSnapshotIdSchema,
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    width: z.number().int().min(1).max(16383),
+    height: z.number().int().min(1).max(16383),
+  })
+  .refine((image) => image.width * image.height <= GEO_SNAPSHOT_MAX_PIXELS, "Map image exceeds decoded pixel budget");
+export const GeoMapSnapshotManifestSchema = z
+  .strictObject({
+    version: z.literal(1),
+    revision: z.string().min(1).max(300),
+    // Even IDs with one character need a 64-byte SHA-256: this bounds schema work independently of input parsing.
+    images: z.array(GeoMapSnapshotImageSchema).max(GEO_SNAPSHOT_MAX_METADATA_BYTES / 64),
+  })
+  .refine((value) => new Set(value.images.map((image) => image.id)).size === value.images.length, "Duplicate map ID");
+export type GeoMapSnapshotManifest = z.infer<typeof GeoMapSnapshotManifestSchema>;
+export const geoMapSnapshotPart = (id: string) => `map-snapshot-${GeoMapSnapshotIdSchema.parse(id)}`;
+
+/** Hash the validated saved GeoDocument, not a lossy geometry projection. Same algorithm in browser and server. */
+export async function geoMapSnapshotFingerprint(value: unknown): Promise<string> {
+  // First enforce genuine JSON (and bound traversal) without invoking caller-defined toJSON/accessors.
+  let remaining = GEO_SNAPSHOT_MAX_METADATA_BYTES;
+  const ancestors = new Set<object>();
+  const canonical = (input: unknown): string => {
+    if (--remaining < 0) throw new RangeError("Map snapshot input exceeds geo JSON budget");
+    if (
+      input === null ||
+      typeof input === "boolean" ||
+      typeof input === "string" ||
+      (typeof input === "number" && Number.isFinite(input))
+    ) {
+      const result = JSON.stringify(input);
+      remaining -= result.length;
+      return result;
+    }
+    if (typeof input !== "object" || !input || ancestors.has(input)) throw new TypeError("Map snapshot input must be JSON");
+    if (!Array.isArray(input) && Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null)
+      throw new TypeError("Map snapshot input must be plain JSON");
+    ancestors.add(input);
+    try {
+      if (Array.isArray(input)) {
+        if (input.length > remaining) throw new RangeError("Map snapshot input exceeds geo JSON budget");
+        const items: string[] = [];
+        for (let index = 0; index < input.length; index++) {
+          const property = Object.getOwnPropertyDescriptor(input, String(index));
+          if (!property || !("value" in property)) throw new TypeError("Map snapshot input must be plain JSON");
+          items.push(canonical(property.value));
+        }
+        return `[${items.join(",")}]`;
+      }
+      return `{${Object.keys(input)
+        .sort()
+        .map((key) => {
+          const property = Object.getOwnPropertyDescriptor(input, key)!;
+          if (!("value" in property)) throw new TypeError("Map snapshot input must not contain accessors");
+          remaining -= key.length;
+          return `${JSON.stringify(key)}:${canonical(property.value)}`;
+        })
+        .join(",")}}`;
+    } finally {
+      ancestors.delete(input);
+    }
+  };
+  let serialized: string;
+  try {
+    serialized = canonical(value);
+  } catch (error) {
+    if (error instanceof RangeError) throw new RangeError("Map snapshot input exceeds geo JSON budget");
+    throw error;
+  }
+  const bytes = new TextEncoder().encode(serialized);
+  if (bytes.byteLength > GEO_SNAPSHOT_MAX_METADATA_BYTES) throw new RangeError("Map snapshot input exceeds geo JSON budget");
+  return Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/src/contracts/geo.ts

@@ -30,6 +30,12 @@ export const GeoAddressSchema = z
     point: GeoPointSchema.describe("Resolved geographic point."),
     formatted: z.string().max(600).describe("Formatted provider address."),
     confidence: z.number().min(0).max(1).nullable().describe("Provider match confidence, or null when unavailable."),
+    buildingConfidence: z
+      .number()
+      .min(0)
+      .max(1)
+      .nullable()
+      .describe("Provider certainty that this point is the requested building; null without a house-number match."),
     provenance: GeoProvenanceSchema.describe("Provider source and required attribution."),
   })
   .strict();
@@ -128,6 +134,13 @@ export const GEO_MAX_POLYLINE_CHARS = 102_400;
 export const GeoPlaceSearchInputSchema = z
   .object({
     categories: z.array(GeoCategorySchema).describe("1–5 Cloud categories."),
+    name: z
+      .string()
+      .trim()
+      .min(1)
+      .max(300)
+      .optional()
+      .describe("Optional provider place-name filter, 1–300 characters after trimming; categories still apply."),
     near: GeoPointSchema.optional().describe("Rank by distance to this point; choose near, area, or along."),
     area: GeoAreaSchema.optional().describe("Optional geographic filter."),
     along: z
@@ -249,6 +262,7 @@ export type GeoAutocompleteInput = z.infer<typeof GeoAutocompleteInputSchema>;
 export type GeoGeocodeInput = z.infer<typeof GeoGeocodeInputSchema>;
 export type GeoReverseInput = z.infer<typeof GeoReverseInputSchema>;
 export type GeoPlaceSearchInput = z.infer<typeof GeoPlaceSearchInputSchema>;
+export type GeoAvailabilityData = z.infer<typeof GeoAvailabilityDataSchema>;
 export type GeoErrorCode = z.infer<typeof GeoErrorDetailsSchema>["code"];
 export type GeoFunction = "autocomplete" | "geocode" | "reverse" | "places" | "route";
 export const geoContract = {

package/src/contracts/index.ts

@@ -10,6 +10,7 @@ export * from "./capabilities";
 export * from "./capability-compatibility";
 export * from "./commands";
 export * from "./contact-directory";
+export * from "./discussions";
 export * from "./file-provider";
 export * from "./geo";
 export * from "./geo-admin";
@@ -29,6 +30,7 @@ export type { RailShortcut } from "./rail-preferences";
 export * from "./registry";
 export * from "./resource-clipboard";
 export { type ResolvedCloudResourceUrl, ResolvedCloudResourceUrlSchema } from "./resource-resolution";
+export * from "./resource-types";
 export * from "./seen-hints";
 export * from "./shared";
 export * from "./user-notifications";

package/src/contracts/outgoing-mail.ts

@@ -2,7 +2,7 @@ import type { PageParams, Paginated, ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
 import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 
-export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read"]);
+export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read", "resources:readers"]);
 export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
 export const MailRetentionSchema = z.object({ contentDays: z.int().min(1).max(36500), recordDays: z.int().min(1).max(36500) }).strict();
 export type MailRetention = z.infer<typeof MailRetentionSchema> & {

package/src/contracts/resource-types.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { type CapabilityManifest, CloudResourceReaderViewSchema } from "./capabilities";
+import { type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+
+/** Check the reader's guaranteed `data.view`; the type model supplies containment. */
+export const typeViewIssues = (
+  manifest: Pick<CapabilityManifest, "types" | "queries" | "resourceTypes">,
+  localId: string,
+): CapabilityContractIssue[] => {
+  const type = manifest.types.find((type) => type.localId === localId);
+  const reader = manifest.queries.find((query) => query.localId === type?.reader);
+  if (!type || !reader) return [{ code: "kind", path: "$", message: `Type ${localId} needs a reader` }];
+  const container = manifest.resourceTypes?.find((model) => model.type === localId)?.container;
+  const view = container ? CloudResourceReaderViewSchema.required({ container: true }) : CloudResourceReaderViewSchema;
+  const issues = capabilityContractIssues(
+    { kind: "query", input: z.object({}).strict(), data: z.looseObject({ view }) },
+    { kind: "query", operation: reader },
+  ).filter((issue) => issue.code !== "input");
+  if (reader.appOnly) issues.push({ code: "kind", path: "$", message: "A resource reader must accept person authority" });
+  return issues;
+};

package/src/contracts/shared.ts

@@ -146,9 +146,10 @@ export const EntityListItemSchema = z.discriminatedUnion("kind", [
 export type EntityListItem = z.infer<typeof EntityListItemSchema>;
 
 export const GroupMemberSchema = z.object({
-  type: z.enum(["user", "group"]),
+  type: z.enum(["user", "group", "service_account"]),
   id: z.string(),
   displayName: z.string().nullable(),
+  serviceAccountKind: ServiceAccountKindSchema.optional(),
 });
 export type GroupMember = z.infer<typeof GroupMemberSchema>;