@k2b/cloud 0.42.0 → 0.44.0

package/src/contracts/app-access.ts

@@ -1,6 +1,8 @@
+import type { SQL } from "bun";
 import { z } from "zod";
 import type { RequestAuthority } from "../server/middleware/auth";
-import { type Role, RoleSchema } from "./shared";
+import type { ResourceAccessAdapter } from "../server/services/access";
+import { AccessEntrySchema, type Role, RoleSchema } from "./shared";
 
 const publicRoutes = z
   .array(
@@ -21,22 +23,41 @@ export const AppAccessRuleSchema = z.union([
   z.object({ kind: z.literal("signedIn"), publicRoutes }).strict(),
   z.object({ kind: z.literal("noGuests"), publicRoutes }).strict(),
   z.object({ kind: z.literal("roles"), roles: z.array(RoleSchema).min(1).readonly(), publicRoutes }).strict(),
+  z.object({ kind: z.literal("resources"), adapters: z.array(z.string().min(1)).min(1).readonly(), publicRoutes }).strict(),
   z.object({ kind: z.literal("grants"), until: FixedAppAccessRuleSchema.optional(), publicRoutes }).strict(),
 ]);
 /** Serializable entry rule evaluated by the platform; never application callback code. */
 export type AppAccessRule = z.infer<typeof AppAccessRuleSchema>;
-/** The optional management restriction runs in the owning application, in addition to a management grant. */
-export type AppAccessDeclaration = AppAccessRule & {
-  canManage?: (authority: RequestAuthority) => boolean | Promise<boolean>;
+/**
+ * The optional management restriction runs in the owning application, in addition to a management grant.
+ * SQL-backed callbacks and domain services they call must use the supplied db: edits hold its transaction connection.
+ */
+export type AppAccessDeclaration = (
+  | Exclude<AppAccessRule, { kind: "resources" }>
+  | {
+      kind: "resources";
+      adapters: Readonly<Record<string, ResourceAppAccessAdapter>>;
+      publicRoutes?: readonly string[];
+    }
+) & {
+  canManage?: (authority: RequestAuthority, context: { db: SQL }) => boolean | Promise<boolean>;
 };
+/** An existence query is required for resource-derived app access; list() cannot answer it without a resource scan. */
+export type ResourceAppAccessAdapter = Required<Pick<ResourceAccessAdapter, "hasAnyRight">>;
 type PublicOptions = { publicRoutes?: readonly string[] };
 export const appAccess = {
+  resources: (
+    options: PublicOptions & { adapters: Readonly<Record<string, ResourceAppAccessAdapter>> },
+  ): Extract<AppAccessDeclaration, { kind: "resources" }> => ({
+    kind: "resources",
+    ...options,
+  }),
   signedIn: (options: PublicOptions = {}): AppAccessRule & { kind: "signedIn" } => ({ kind: "signedIn", ...options }),
   noGuests: (options: PublicOptions = {}): AppAccessRule & { kind: "noGuests" } => ({ kind: "noGuests", ...options }),
   roles: (roles: readonly Role[], options: PublicOptions = {}): AppAccessRule & { kind: "roles" } => ({ kind: "roles", roles, ...options }),
   grants: (
     options: PublicOptions & { until?: FixedAppAccessRule; canManage?: AppAccessDeclaration["canManage"] } = {},
-  ): AppAccessDeclaration => ({ kind: "grants", ...options }),
+  ): Extract<AppAccessDeclaration, { kind: "grants" }> => ({ kind: "grants", ...options }),
 };
 
 export const compileAppAccess = (declaration: AppAccessDeclaration | undefined): AppAccessRule | undefined => {
@@ -44,5 +65,31 @@ export const compileAppAccess = (declaration: AppAccessDeclaration | undefined):
   const { canManage, ...rule } = declaration;
   if (canManage && (rule.kind !== "grants" || typeof canManage !== "function"))
     throw new Error("Only configurable app access accepts canManage");
+  if (rule.kind === "resources") {
+    if (Array.isArray(rule.adapters)) throw new Error("Declare resource adapters, not registry metadata");
+    for (const adapter of Object.values(rule.adapters)) {
+      if (typeof adapter.hasAnyRight !== "function") throw new Error("Resource app access requires hasAnyRight on every adapter");
+    }
+    return AppAccessRuleSchema.parse({ ...rule, adapters: Object.keys(rule.adapters) });
+  }
   return AppAccessRuleSchema.parse(rule);
 };
+
+export const AppAccessSnapshotSchema = z.object({
+  appId: z.string(),
+  name: z.string(),
+  entries: z.array(
+    AccessEntrySchema.extend({
+      id: z.union([z.uuid(), z.literal("inherited-authenticated")]),
+      groupMemberCount: z.number().int().nonnegative().optional(),
+      /** Platform eligibility for presentation; the server still checks any app-owned restriction. */
+      effectiveManager: z.boolean().optional(),
+    }),
+  ),
+  ownEntryIds: z.array(z.string()),
+  configured: z.boolean(),
+  hasEffectiveManager: z.boolean(),
+  inheritedSignedIn: z.boolean(),
+  canUse: z.boolean(),
+});
+export type AppAccessSnapshot = z.infer<typeof AppAccessSnapshotSchema>;

package/src/contracts/app-approval.ts

@@ -265,7 +265,14 @@ export const AppPendingLoginSchema = z
   })
   .strict();
 export const AppPairingPayloadSchema = z
-  .object({ protocol: z.literal(APP_APPROVAL_PROTOCOL), issuer: z.string().url(), pairingId: Id, secret: Secret, expiresAt: DateTime })
+  .object({
+    protocol: z.literal(APP_APPROVAL_PROTOCOL),
+    issuer: z.string().url(),
+    pairingId: Id,
+    secret: Secret,
+    expiresAt: DateTime,
+    label: z.string().trim().min(1).max(80).optional(),
+  })
   .strict();
 export type AppPairingPayload = z.infer<typeof AppPairingPayloadSchema>;
 

package/src/contracts/app-details.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { PlatformPermissionSchema } from "./outgoing-mail";
+import { RoleSchema } from "./shared";
+
+/** Match the administrative event API's maximum page size. Totals make truncation visible. */
+export const APP_DETAILS_LIST_LIMIT = 100;
+export const APP_DETAILS_FAILED_LIMIT = 5;
+export const APP_SUBSCRIPTION_NEW_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+const count = z.number().int().nonnegative();
+const deliveryCounts = z.object({ pending: count, retrying: count, done: count, failed: count, cancelled: count });
+
+export const AppDetailsSchema = z.object({
+  app: z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable(),
+    icon: z.string().nullable(),
+    accent: z.templateLiteral(["#", z.string()]).nullable(),
+    online: z.boolean(),
+  }),
+  access: z.object({
+    /** Null means Core has no current access declaration for an offline app. */
+    kind: z.enum(["grants", "signedIn", "noGuests", "roles", "resources", "legacy"]).nullable(),
+    roles: z.array(RoleSchema),
+    grantCount: count.nullable(),
+    platformPermissions: z.array(PlatformPermissionSchema),
+  }),
+  sends: z
+    .array(
+      z.object({
+        type: z.string(),
+        version: z.number().int().positive(),
+        title: z.string(),
+        description: z.string(),
+        subject: z.string(),
+        place: z.string().nullable(),
+        automation: z.boolean(),
+        subscriberCount: count,
+      }),
+    )
+    .max(APP_DETAILS_LIST_LIMIT),
+  hears: z
+    .array(
+      z.object({
+        subscriptionId: z.string(),
+        eventType: z.string(),
+        version: z.number().int().positive(),
+        publisherAppId: z.string(),
+        title: z.string().nullable(),
+        state: z.enum(["active", "blocked", "cancelled"]),
+        reason: z.string().nullable(),
+        firstSeenAt: z.iso.datetime(),
+        isNew: z.boolean(),
+        counts: deliveryCounts,
+        failedDeliveries: z
+          .array(
+            z.object({
+              id: z.uuid(),
+              eventId: z.uuid(),
+              code: z.string().nullable(),
+              lastError: z.string().max(1000).nullable(),
+              attempts: count,
+              lastAttemptAt: z.iso.datetime().nullable(),
+            }),
+          )
+          .max(APP_DETAILS_FAILED_LIMIT),
+      }),
+    )
+    .max(APP_DETAILS_LIST_LIMIT),
+  notifications: z
+    .array(
+      z.object({
+        id: z.string(),
+        kind: z.string(),
+        label: z.string(),
+        description: z.string(),
+        recipientKind: z.enum(["user", "email"]),
+        requiredChannels: z.array(z.string()),
+        recommendedChannels: z.array(z.string()),
+        excludedChannels: z.array(z.string()),
+        excludedReason: z.string().nullable(),
+      }),
+    )
+    .max(APP_DETAILS_LIST_LIMIT),
+  totals: z.object({ sends: count, hears: count, notifications: count }),
+});
+
+export type AppDetails = z.infer<typeof AppDetailsSchema>;

package/src/contracts/app-events.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { CapabilityAppIdSchema, CapabilityQualifiedIdSchema, CloudResourceRefSchema } from "./capabilities";
+
+/** Maximum PostgreSQL jsonb-text size of the complete envelope, including separator spaces. */
+export const APP_EVENT_MAX_BYTES = 4096;
+
+export const AppEventEnvelopeSchema = z
+  .object({
+    id: z.uuid(),
+    type: CapabilityQualifiedIdSchema,
+    version: z.number().int().positive(),
+    source: CapabilityAppIdSchema,
+    time: z.iso.datetime({ offset: true }),
+    subject: CloudResourceRefSchema,
+    place: CloudResourceRefSchema.optional(),
+    cause: z
+      .object({ requestId: z.string().min(1).max(256) })
+      .strict()
+      .optional(),
+    data: z.json(),
+  })
+  .strict();
+
+export type AppEventEnvelope<Data = unknown> = Omit<z.infer<typeof AppEventEnvelopeSchema>, "data"> & { data: Data };
+
+/** Delivery runs as the subscribing service, without a user's request authority. */
+export type AppEventDeliveryContext = {
+  subscriptionId: string;
+  eventId: string;
+  attempt: number;
+  signal: AbortSignal;
+};
+
+export type AppEventDefinition<Schema extends z.ZodType = z.ZodType> = {
+  version: number;
+  title: string;
+  description: string;
+  subject: string;
+  place?: string;
+  schema: Schema;
+  automation?: false;
+};
+
+export type AppEventSubscriptionDefinition<Schema extends z.ZodType = z.ZodType> = {
+  version: number;
+  schema: Schema;
+  run(envelope: AppEventEnvelope<z.output<Schema>>, context: AppEventDeliveryContext): unknown | Promise<unknown>;
+};
+
+export const appEventSubscriptionId = (subscriber: string, type: string, version: number): string =>
+  `${CapabilityAppIdSchema.parse(subscriber)}:${CapabilityQualifiedIdSchema.parse(type)}@${z.number().int().positive().parse(version)}`;

package/src/contracts/app.ts

@@ -1,5 +1,6 @@
 import type { Sync } from "@k2b/sync";
 import type { AppAccessRule } from "./app-access";
+import type { AppInstallable } from "./installable";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
@@ -49,9 +50,16 @@ export type AppAdminNavigationLink = {
   icon: string;
 };
 
+/** Platform admin areas an app can contribute to with `adminNav[].section`. */
+export const APP_ADMIN_AREAS = ["ai", "observability"] as const;
+export type AppAdminArea = (typeof APP_ADMIN_AREAS)[number];
+
 export type AppAdminNavigationGroup = {
-  /** Contribute links to the platform AI section instead of a separate group. */
-  section?: "ai";
+  /**
+   * Contribute links to a platform admin area instead of a separate group. The admin sidebar shows the area as one
+   * entry; the owner renders the area's columns itself. `"ai"` is the AI area, `"observability"` the Observability area.
+   */
+  section?: AppAdminArea;
   /** Stable key used only to localize this presentation group. */
   id?: string;
   label: string;
@@ -108,6 +116,10 @@ export type AppPwaPart = {
   href: string;
   /** Coarse visibility in the mobile app, like `nav.requiresRoles`. Routes and services still authorize. */
   requiresRoles?: Role[];
+  /** Same-origin path of a `GET` route returning an `AppNavBadge`, counted beside the part in the app's sidebar. */
+  badge?: string;
+  /** Same-origin path of a `GET` route returning a `PwaPartSummary`, the line under the part on the app's Start. */
+  summary?: string;
 };
 
 /** One same-origin panel page contributed by an application. Routes and services still authorize. */
@@ -126,6 +138,8 @@ export type AppMeta = {
   access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;
+  /** Shared object-store package; omitted means the app ID. */
+  package?: string;
   name: string;
   icon: string;
   description: string;
@@ -158,6 +172,8 @@ export type AppMeta = {
   searchLinks?: readonly AppSearchLink[];
   /** The app's pages in the installable mobile app (preview), at `href` = `/pwa/<id>`. */
   pwa?: AppPwaPart;
+  /** One standalone installation under this app's own declared route. */
+  installable?: AppInstallable;
   panel?: AppPanel;
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
@@ -177,12 +193,15 @@ export type AppMeta = {
 
 /**
  * Response of an app's `nav.badge` route: how many items wait for the signed-in
- * person. A positive safe integer shows a count on the app's icon in the rail
- * and the app grid (above 99 as "99+"); `0`, a non-200 response, or anything
- * else shows none.
+ * person. A positive safe integer shows a count on the app's icon in the rail,
+ * the phone bar, and the app grid (above 99 as "99+"); `0`, a non-200
+ * response, or anything else shows none.
  */
 export type AppNavBadge = { count: number };
 
+/** What a part says about itself on the Cloud app's Start: a line in the reader's locale and the count behind it. */
+export type PwaPartSummary = AppNavBadge & { text: string };
+
 /** A widget endpoint and its board presentation; the handler owns resource authorization. */
 export type WidgetEndpoint = {
   /** Unique-within-the-app id, e.g. "open-requests". */

package/src/contracts/calendar-source.ts

@@ -0,0 +1,274 @@
+import { z } from "zod";
+import { type CapabilityManifest, CapabilitySemanticLinkSchema, CloudResourceRefSchema } from "./capabilities";
+import { type CapabilityContract, type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
+
+/** Elapsed time, matching Spaces agenda's public 31-day request budget. */
+export const CALENDAR_SOURCE_MAX_RANGE_MS = 31 * 24 * 60 * 60 * 1000;
+/** Spaces agenda's 100-item page; providers must also fit the 256 KiB capability result budget. */
+export const CALENDAR_SOURCE_PAGE_LIMIT = 100;
+/** Stale writes fail with HTTP 409. Sources never overwrite a different version. */
+export const CALENDAR_VERSION_CONFLICT = "CALENDAR_VERSION_CONFLICT";
+
+// Same opaque ID/cursor and display-text budgets as file providers and capability links.
+// Field bounds limit individual allocations; they do not replace the 256 KiB page budget.
+const IdSchema = z.string().min(1).max(2048).describe("Opaque source identifier or version.");
+const CursorSchema = z.string().min(1).max(16384).describe("Opaque continuation cursor; keep the other inputs unchanged.");
+const TimestampSchema = z.string().datetime({ offset: true }).describe("Timestamp with an explicit UTC offset.");
+const DateSchema = z.iso.date().describe("Date in the source configured date/time zone.");
+const TimeZoneSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .refine((zone) => {
+    try {
+      // Intl also accepts fixed offsets; the contract requires a named IANA zone.
+      return !/^[+-]/.test(new Intl.DateTimeFormat("en", { timeZone: zone }).resolvedOptions().timeZone);
+    } catch {
+      return false;
+    }
+  }, "Expected an IANA time zone")
+  .describe("IANA time zone, or null for an instant without a display zone.");
+const OpenSchema = CapabilitySemanticLinkSchema.extend({ rel: z.literal("open") }).loose();
+const LimitSchema = z.number().int().min(1).max(CALENDAR_SOURCE_PAGE_LIMIT).optional().describe("Maximum page size, between 1 and 100.");
+
+export const CalendarListInputSchema = z.object({ cursor: CursorSchema.optional(), limit: LimitSchema }).strict();
+export const CalendarDescriptorSchema = z
+  .object({
+    id: IdSchema,
+    name: z.string().min(1).max(200),
+    description: z.string().max(500).optional(),
+    color: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{6}$/)
+      .optional(),
+    suggested: z.boolean(),
+    visibility: z.enum(["details", "busy"]),
+    writable: z.boolean(),
+    open: OpenSchema.optional(),
+  })
+  .loose();
+export const CalendarListDataSchema = z
+  .object({ items: z.array(CalendarDescriptorSchema).max(CALENDAR_SOURCE_PAGE_LIMIT), next: CursorSchema.nullable() })
+  .loose();
+
+/** Half-open [from, to): events overlap it; deadlines have a due point inside it. */
+export const CalendarEventsInputSchema = z
+  .object({
+    calendarIds: z
+      .array(IdSchema)
+      .min(1)
+      .max(CALENDAR_SOURCE_PAGE_LIMIT)
+      .describe("Readable calendar IDs to include; unknown or unreadable IDs are omitted."),
+    from: TimestampSchema,
+    to: TimestampSchema,
+    cursor: CursorSchema.optional(),
+    limit: LimitSchema,
+  })
+  .strict()
+  .refine((input) => Date.parse(input.to) > Date.parse(input.from), "to must be after from")
+  .refine((input) => Date.parse(input.to) - Date.parse(input.from) <= CALENDAR_SOURCE_MAX_RANGE_MS, "Range exceeds 31 elapsed days");
+
+const EventDateSchema = z
+  .object({ kind: z.literal("date").describe("Date-only time."), start: DateSchema, end: DateSchema })
+  .loose()
+  .refine((time) => time.end > time.start, "Date end must be exclusive and after start");
+const EventInstantSchema = z
+  .object({
+    kind: z.literal("instant").describe("Time with an explicit offset."),
+    start: TimestampSchema,
+    end: TimestampSchema,
+    timeZone: TimeZoneSchema.nullable().describe("IANA display zone, or null."),
+  })
+  .loose()
+  .refine((time) => Date.parse(time.end) >= Date.parse(time.start), "End must not precede start");
+/** Date-only values use the source's configured date/time zone; floating instants are forbidden. */
+export const CalendarEventTimeSchema = z.discriminatedUnion("kind", [EventDateSchema, EventInstantSchema]);
+const DueDateSchema = z.object({ kind: z.literal("date").describe("Date-only time."), date: DateSchema }).loose();
+const DueInstantSchema = z
+  .object({
+    kind: z.literal("instant").describe("Time with an explicit offset."),
+    at: TimestampSchema,
+    timeZone: TimeZoneSchema.nullable().describe("IANA display zone, or null."),
+  })
+  .loose();
+export const CalendarDueTimeSchema = z.discriminatedUnion("kind", [DueDateSchema, DueInstantSchema]);
+export const CalendarOccurrenceSchema = z
+  .object({
+    seriesId: IdSchema,
+    originalStart: z.union([TimestampSchema, DateSchema]),
+    // Display only: the source expands recurrence. A 1000-character RRULE fits the capability display budget.
+    rule: z.string().max(1000).nullable(),
+  })
+  .loose();
+const identity = { id: IdSchema, calendarId: IdSchema };
+const details = {
+  ...identity,
+  title: z.string().max(500),
+  occurrence: CalendarOccurrenceSchema.nullable(),
+  ref: CloudResourceRefSchema.loose().nullable(),
+  open: OpenSchema.nullable(),
+  version: IdSchema,
+};
+const eventState = { status: z.enum(["confirmed", "cancelled"]), transparency: z.enum(["busy", "free"]) };
+export const CalendarItemSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("event"),
+      ...details,
+      time: CalendarEventTimeSchema,
+      location: z.string().max(500).nullable(),
+      ...eventState,
+    })
+    .loose(),
+  z.object({ type: z.literal("deadline"), ...details, due: CalendarDueTimeSchema, done: z.boolean() }).loose(),
+  z.object({ type: z.literal("busy"), ...identity, time: CalendarEventTimeSchema, ...eventState }).loose(),
+]);
+export const CalendarEventsDataSchema = z
+  .object({ items: z.array(CalendarItemSchema).max(CALENDAR_SOURCE_PAGE_LIMIT), next: CursorSchema.nullable() })
+  .loose();
+
+const writeIdentity = {
+  ...identity,
+  version: IdSchema,
+  scope: z.enum(["occurrence", "series"]).optional().describe("Recurring write target; the source requires a scope for recurring items."),
+};
+export const CalendarUpdateInputSchema = z
+  .object({
+    ...writeIdentity,
+    changes: z
+      .object({
+        title: z.string().max(500).optional().describe("Replacement title."),
+        location: z.string().max(500).nullable().optional().describe("Replacement location; null clears it."),
+        done: z.boolean().optional().describe("Replacement deadline completion state."),
+      })
+      .strict()
+      .describe("Fields to update; the source validates which apply to the item."),
+  })
+  .strict();
+export const CalendarMoveInputSchema = z
+  .object({
+    ...writeIdentity,
+    time: z
+      .discriminatedUnion("kind", [EventDateSchema.strict(), EventInstantSchema.strict()])
+      .optional()
+      .describe("Replacement event time; mutually exclusive with due."),
+    due: z
+      .discriminatedUnion("kind", [DueDateSchema.strict(), DueInstantSchema.strict()])
+      .optional()
+      .describe("Replacement deadline due point; mutually exclusive with time."),
+  })
+  .strict()
+  .refine((input) => (input.time === undefined) !== (input.due === undefined), "Provide exactly one of time or due");
+export const CalendarDeleteInputSchema = z.object(writeIdentity).strict();
+export const CalendarUpdateDataSchema = z.object({ item: CalendarItemSchema }).loose();
+export const CalendarMoveDataSchema = CalendarUpdateDataSchema;
+export const CalendarDeleteDataSchema = z.object({}).loose();
+
+/** Queries have no streams and openWorld:false. Reserved writes require idempotency keys and current versions. */
+export const calendarSource = {
+  calendars: { kind: "query", input: CalendarListInputSchema, data: CalendarListDataSchema },
+  events: { kind: "query", input: CalendarEventsInputSchema, data: CalendarEventsDataSchema },
+  update: { kind: "action", idempotency: "required", input: CalendarUpdateInputSchema, data: CalendarUpdateDataSchema },
+  move: { kind: "action", idempotency: "required", input: CalendarMoveInputSchema, data: CalendarMoveDataSchema },
+  delete: { kind: "action", idempotency: "required", input: CalendarDeleteInputSchema, data: CalendarDeleteDataSchema },
+} as const satisfies Record<string, CapabilityContract>;
+export type CalendarSourceFunction = keyof typeof calendarSource;
+export const CALENDAR_SOURCE_FUNCTIONS = [
+  "calendars",
+  "events",
+  "update",
+  "move",
+  "delete",
+] as const satisfies readonly CalendarSourceFunction[];
+export type CalendarSourceIssue = CapabilityContractIssue & { function: CalendarSourceFunction; localId: string };
+export const calendarSourceIssues = (manifest: CapabilityManifest): CalendarSourceIssue[] => {
+  const declaration = manifest.calendarSource;
+  if (!declaration) return [];
+  return CALENDAR_SOURCE_FUNCTIONS.flatMap((name) => {
+    const localId = declaration[name];
+    if (localId === undefined) return [];
+    const query = manifest.queries.find((operation) => operation.localId === localId);
+    const action = manifest.actions.find((operation) => operation.localId === localId);
+    const issues: CapabilityContractIssue[] = query
+      ? capabilityContractIssues(calendarSource[name], { kind: "query", operation: query })
+      : action
+        ? capabilityContractIssues(calendarSource[name], { kind: "action", operation: action })
+        : [{ code: "kind", path: "$", message: `No Query or Action named ${localId}` }];
+    if ((query ?? action)?.openWorld) issues.push({ code: "kind", path: "$", message: "Calendar operations must have openWorld: false" });
+    if (name === "delete" && action && !action.destructive)
+      issues.push({ code: "kind", path: "$", message: "Calendar delete must be destructive" });
+    return issues.map((issue) => ({ ...issue, function: name, localId }));
+  });
+};
+
+export type CalendarListInput = z.output<typeof CalendarListInputSchema>;
+export type CalendarDescriptor = z.output<typeof CalendarDescriptorSchema>;
+export type CalendarListData = z.output<typeof CalendarListDataSchema>;
+export type CalendarEventsInput = z.output<typeof CalendarEventsInputSchema>;
+export type CalendarEventTime = z.output<typeof CalendarEventTimeSchema>;
+export type CalendarDueTime = z.output<typeof CalendarDueTimeSchema>;
+export type CalendarOccurrence = z.output<typeof CalendarOccurrenceSchema>;
+export type CalendarItem = z.output<typeof CalendarItemSchema>;
+export type CalendarEventsData = z.output<typeof CalendarEventsDataSchema>;
+export type CalendarUpdateInput = z.output<typeof CalendarUpdateInputSchema>;
+export type CalendarMoveInput = z.output<typeof CalendarMoveInputSchema>;
+export type CalendarDeleteInput = z.output<typeof CalendarDeleteInputSchema>;
+export type CalendarUpdateData = z.output<typeof CalendarUpdateDataSchema>;
+export type CalendarMoveData = z.output<typeof CalendarMoveDataSchema>;
+export type CalendarDeleteData = z.output<typeof CalendarDeleteDataSchema>;
+
+const projectTime = (time: CalendarEventTime): CalendarEventTime =>
+  time.kind === "date"
+    ? { kind: "date", start: time.start, end: time.end }
+    : { kind: "instant", start: time.start, end: time.end, timeZone: time.timeZone };
+const projectOpen = (open: z.output<typeof OpenSchema>) => ({
+  rel: open.rel,
+  href: open.href,
+  ...(open.title === undefined ? {} : { title: open.title }),
+});
+/** Readers discard every unrecognized field, including nested fields and all details on busy items. */
+export const projectCalendarItem = (item: CalendarItem): CalendarItem => {
+  const identity = { id: item.id, calendarId: item.calendarId };
+  if (item.type === "busy")
+    return { type: "busy", ...identity, time: projectTime(item.time), status: item.status, transparency: item.transparency };
+  const details = {
+    ...identity,
+    title: item.title,
+    version: item.version,
+    occurrence: item.occurrence && {
+      seriesId: item.occurrence.seriesId,
+      originalStart: item.occurrence.originalStart,
+      rule: item.occurrence.rule,
+    },
+    ref: item.ref && { type: item.ref.type, id: item.ref.id },
+    open: item.open && projectOpen(item.open),
+  };
+  return item.type === "event"
+    ? {
+        type: "event",
+        ...details,
+        time: projectTime(item.time),
+        location: item.location,
+        status: item.status,
+        transparency: item.transparency,
+      }
+    : {
+        type: "deadline",
+        ...details,
+        done: item.done,
+        due:
+          item.due.kind === "date"
+            ? { kind: "date", date: item.due.date }
+            : { kind: "instant", at: item.due.at, timeZone: item.due.timeZone },
+      };
+};
+export const projectCalendarDescriptor = (calendar: CalendarDescriptor): CalendarDescriptor => ({
+  id: calendar.id,
+  name: calendar.name,
+  suggested: calendar.suggested,
+  visibility: calendar.visibility,
+  writable: calendar.writable,
+  ...(calendar.description === undefined ? {} : { description: calendar.description }),
+  ...(calendar.color === undefined ? {} : { color: calendar.color }),
+  ...(calendar.open === undefined ? {} : { open: projectOpen(calendar.open) }),
+});

package/src/contracts/calendar-view.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { CALENDAR_SOURCE_PAGE_LIMIT, CalendarDescriptorSchema, CalendarItemSchema } from "./calendar-source";
+import { CapabilityAppIdSchema } from "./capabilities";
+
+/** Interactive calendar request budget: six elapsed weeks. */
+export const CALENDAR_VIEW_MAX_RANGE_MS = 42 * 24 * 60 * 60 * 1000;
+export const CalendarViewRangeSchema = z
+  .object({ from: z.string().datetime({ offset: true }), to: z.string().datetime({ offset: true }) })
+  .strict()
+  .refine(({ from, to }) => Date.parse(to) > Date.parse(from), "to must be after from")
+  .refine(({ from, to }) => Date.parse(to) - Date.parse(from) <= CALENDAR_VIEW_MAX_RANGE_MS, "Range exceeds 42 elapsed days");
+export const CalendarSourceErrorSchema = z.object({ code: z.string(), retryable: z.boolean() });
+export const CalendarSourceStateSchema = z.enum(["ok", "pending", "failed", "truncated"]);
+export const CalendarSourceSummarySchema = z.object({
+  appId: CapabilityAppIdSchema,
+  state: CalendarSourceStateSchema,
+  error: CalendarSourceErrorSchema.nullable(),
+});
+export const CalendarSourceListEntrySchema = z.object({
+  appId: CapabilityAppIdSchema,
+  name: z.string(),
+  icon: z.string().nullable(),
+  state: z.enum(["ok", "failed"]),
+  error: CalendarSourceErrorSchema.nullable(),
+  calendars: z.array(CalendarDescriptorSchema).max(CALENDAR_SOURCE_PAGE_LIMIT),
+});
+export const CalendarReadResultSchema = z.object({
+  items: z.array(CalendarItemSchema.and(z.object({ appId: CapabilityAppIdSchema }))),
+  sources: z.array(CalendarSourceSummarySchema),
+});
+export type CalendarSourceState = z.output<typeof CalendarSourceStateSchema>;
+export type CalendarSourceSummary = z.output<typeof CalendarSourceSummarySchema>;
+export type CalendarSourceListEntry = z.output<typeof CalendarSourceListEntrySchema>;
+export type CalendarReadResult = z.output<typeof CalendarReadResultSchema>;
+export type CalendarSelection = { appId: string; calendarId: string };