@k2b/cloud 0.40.0 → 0.42.0

package/src/contracts/geo-route.ts

@@ -0,0 +1,168 @@
+import { z } from "zod";
+import { GEO_MAX_POLYLINE_CHARS, GeoAddressSchema, GeoGeocodeInputSchema, GeoPointSchema, GeoProvenanceSchema } from "./geo";
+
+export const GEO_ROUTE_MAX_STOPS = 26;
+export const GeoRouteDistanceAllowanceSchema = z
+  .number()
+  .int()
+  .min(1)
+  .max(1_000_000_000)
+  .describe(
+    "Reference distance allowance in meters per leg; defaults to 500000. The whole chain reserves at this allowance. This is not a guaranteed provider bill ceiling. A larger actual route is charged and stops the chain.",
+  );
+const stopId = z.string().min(1).max(100).describe("Stable stop ID, unique within this route.");
+export const GeoRouteOptionsSchema = z
+  .object({
+    mode: z.enum(["car", "bike", "walk"]).optional().describe("Travel mode; defaults to car."),
+    avoid: z
+      .array(z.enum(["tolls", "ferries", "highways"]))
+      .max(3)
+      .optional()
+      .describe("Preferences, not prohibitions; tolls/highways require car. Each preference costs extra."),
+  })
+  .strict();
+export const GeoRouteStopSchema = z
+  .object({
+    id: stopId,
+    label: z.string().max(300).optional().describe("Optional display label."),
+    point: GeoPointSchema.optional().describe("Known coordinates; choose point or address."),
+    address: GeoGeocodeInputSchema.optional().describe("Address to resolve; choose address or point. Ambiguity returns candidates."),
+  })
+  .strict();
+export const GeoRouteResolvedStopSchema = z
+  .object({
+    id: stopId,
+    label: z.string().max(300).optional().describe("Optional display label."),
+    point: GeoPointSchema.describe("Resolved stop coordinates."),
+    address: GeoAddressSchema.optional().describe("Resolved address, when this stop was geocoded."),
+  })
+  .strict();
+export const GeoRouteLegOptionsSchema = z
+  .object({
+    fromStopId: stopId,
+    toStopId: stopId,
+    options: GeoRouteOptionsSchema.describe("Override only the supplied options for this adjacent pair."),
+  })
+  .strict();
+export const GeoRoutePlanSchema = z
+  .object({
+    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema.optional(),
+    stops: z.array(GeoRouteStopSchema).min(2).max(GEO_ROUTE_MAX_STOPS).describe("2–26 stops in travel order, with unique IDs."),
+    options: GeoRouteOptionsSchema.optional().describe("Default options for the route."),
+    legOptions: z
+      .array(GeoRouteLegOptionsSchema)
+      .max(25)
+      .optional()
+      .describe("Options for adjacent stop pairs; on move/optimization each override travels with its departure stop."),
+    optimize: z.boolean().optional().describe("Optimize intermediate stops; start and destination stay fixed."),
+  })
+  .strict();
+const geometry = z.string().min(2).max(GEO_MAX_POLYLINE_CHARS);
+export const GeoRouteLegSchema = z
+  .object({
+    fromStopId: stopId,
+    toStopId: stopId,
+    options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
+    distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+    durationSeconds: z.number().nonnegative().describe("Estimated travel duration in seconds, without live traffic."),
+    polyline6: geometry.describe("Encoded route geometry at precision six."),
+    simplificationToleranceMeters: z.number().nonnegative().describe("Conservative geometry simplification tolerance in meters."),
+    provenance: GeoProvenanceSchema.describe("Provider provenance and required attribution."),
+  })
+  .strict();
+export const GeoRouteSchema = z
+  .object({
+    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema,
+    stops: z.array(GeoRouteResolvedStopSchema).min(2).max(GEO_ROUTE_MAX_STOPS).describe("Resolved stops in current travel order."),
+    options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
+    legs: z.array(GeoRouteLegSchema).min(1).max(25).describe("Independent stopover legs in travel order."),
+    distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+    durationSeconds: z.number().nonnegative().describe("Estimated travel duration in seconds, without live traffic."),
+    polyline6: geometry.describe("Encoded route geometry at precision six."),
+    simplificationToleranceMeters: z.number().nonnegative().describe("Conservative geometry simplification tolerance in meters."),
+    inputHash: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .describe("SHA-256 fingerprint of the resolved route input; preserve when updating."),
+    provenance: GeoProvenanceSchema.describe("Provider provenance and required attribution."),
+  })
+  .strict()
+  .describe("Self-contained stateless route; preserve stops, legs, options and provenance when saving.");
+export const GeoRouteChangesSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("insert").describe("Insert one stop."),
+      stop: GeoRouteStopSchema.describe("New stop to insert."),
+      afterStopId: stopId.optional().describe("Insert after this stop; omit to compare up to three best candidate gaps."),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("move").describe("Move an existing stop to a new index."),
+      stopId,
+      toIndex: z.number().int().min(0).max(25).describe("Zero-based destination index in the final stop order."),
+    })
+    .strict(),
+  z.object({ type: z.literal("optimize").describe("Optimize intermediate stop order while fixing start and destination.") }).strict(),
+  z
+    .object({
+      type: z.literal("options").describe("Change route defaults or one leg."),
+      options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
+      leg: z
+        .object({ fromStopId: stopId, toStopId: stopId })
+        .strict()
+        .optional()
+        .describe("Change just this adjacent pair; omit to change route defaults and clear leg overrides."),
+    })
+    .strict(),
+]);
+export const GeoRouteCalculateInputSchema = z.object({ plan: GeoRoutePlanSchema.describe("Route stops and travel preferences.") }).strict();
+export const GeoRouteCalculateDataSchema = z.object({ route: GeoRouteSchema }).strict();
+export const GeoRouteUpdateInputSchema = z
+  .object({
+    route: GeoRouteSchema,
+    changes: GeoRouteChangesSchema.describe("One stateless route edit to preview."),
+    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema.optional(),
+  })
+  .strict();
+export const GeoRouteUpdateDataSchema = z
+  .object({
+    route: GeoRouteSchema,
+    before: z
+      .object({
+        stopIds: z.array(stopId).min(2).max(26),
+        distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+        durationSeconds: z.number().nonnegative(),
+      })
+      .strict(),
+    after: z
+      .object({
+        stopIds: z.array(stopId).min(2).max(26),
+        distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+        durationSeconds: z.number().nonnegative(),
+      })
+      .strict(),
+    delta: z.object({ distanceMeters: z.number(), durationSeconds: z.number() }).strict(),
+    insertion: z
+      .object({ afterStopId: stopId, candidateGaps: z.number().int().min(1).max(3), exhaustive: z.boolean() })
+      .strict()
+      .optional()
+      .describe("Best insertion is a three-gap heuristic when there are more than three gaps."),
+  })
+  .strict();
+export type GeoRouteOptions = z.infer<typeof GeoRouteOptionsSchema>;
+export type GeoRouteStop = z.infer<typeof GeoRouteStopSchema>;
+export type GeoRouteResolvedStop = z.infer<typeof GeoRouteResolvedStopSchema>;
+export type GeoRouteLegOptions = z.infer<typeof GeoRouteLegOptionsSchema>;
+export type GeoRoutePlan = z.infer<typeof GeoRoutePlanSchema>;
+export type GeoRouteLeg = z.infer<typeof GeoRouteLegSchema>;
+export type GeoRoute = z.infer<typeof GeoRouteSchema>;
+export type GeoRouteChanges = z.infer<typeof GeoRouteChangesSchema>;
+export type GeoRouteCalculateInput = z.infer<typeof GeoRouteCalculateInputSchema>;
+export type GeoRouteCalculateData = z.infer<typeof GeoRouteCalculateDataSchema>;
+export type GeoRouteUpdateInput = z.infer<typeof GeoRouteUpdateInputSchema>;
+export type GeoRouteUpdateData = z.infer<typeof GeoRouteUpdateDataSchema>;
+export const geoRouteContract = {
+  calculateRoute: { id: "route.calculate", input: GeoRouteCalculateInputSchema, data: GeoRouteCalculateDataSchema },
+  updateRoute: { id: "route.update", input: GeoRouteUpdateInputSchema, data: GeoRouteUpdateDataSchema },
+} as const;

package/src/contracts/geo.ts

@@ -0,0 +1,248 @@
+import { z } from "zod";
+
+export const GeoPointSchema = z
+  .object({
+    lat: z.number().min(-90).max(90).describe("Latitude in degrees, -90 to 90."),
+    lon: z.number().min(-180).max(180).describe("Longitude in degrees, -180 to 180."),
+  })
+  .strict();
+export const GeoProvenanceSchema = z
+  .object({
+    provider: z.literal("geoapify").describe("Source provider."),
+    attribution: z
+      .object({
+        text: z.literal("Geoapify · OpenStreetMap").describe("Attribution to display with this result."),
+        links: z.array(z.url()).length(2).describe("Provider and data-source attribution links."),
+      })
+      .strict()
+      .describe("Required attribution; preserve when storing or reusing the result."),
+    computedAt: z.iso.datetime().describe("ISO timestamp when the provider result was computed."),
+  })
+  .strict();
+const text = z.string().max(300);
+export const GeoAddressSchema = z
+  .object({
+    line1: text.describe("Street and house number."),
+    postalCode: text.describe("Postal code."),
+    city: text.describe("City or locality."),
+    stateRegion: text.describe("State or region."),
+    countryCode: z.string().max(2).describe("ISO alpha-2 country code, or empty when unavailable."),
+    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."),
+    provenance: GeoProvenanceSchema.describe("Provider source and required attribution."),
+  })
+  .strict();
+
+/** Verified Places categories; names belong to Cloud, provider keys to the adapter. */
+export const GEO_CATEGORIES = {
+  museum: "entertainment.museum",
+  cafe: "catering.cafe",
+  restaurant: "catering.restaurant",
+  bar: "catering.bar",
+  pub: "catering.pub",
+  bakery: "commercial.food_and_drink.bakery",
+  supermarket: "commercial.supermarket",
+  pharmacy: "healthcare.pharmacy",
+  hotel: "accommodation.hotel",
+  accommodation: "accommodation",
+  fuel: "service.vehicle.fuel",
+  parking: "parking",
+  charging: "service.vehicle.charging_station",
+  toilets: "amenity.toilet",
+  park: "leisure.park",
+  viewpoint: "tourism.attraction.viewpoint",
+  attraction: "tourism.attraction",
+} as const;
+export const GeoCategorySchema = z.enum([
+  "museum",
+  "cafe",
+  "restaurant",
+  "bar",
+  "pub",
+  "bakery",
+  "supermarket",
+  "pharmacy",
+  "hotel",
+  "accommodation",
+  "fuel",
+  "parking",
+  "charging",
+  "toilets",
+  "park",
+  "viewpoint",
+  "attraction",
+]);
+export const GeoAreaSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("bbox").describe("Bounding box."),
+      west: z.number().describe("Western longitude."),
+      south: z.number().describe("Southern latitude."),
+      east: z.number().describe("Eastern longitude."),
+      north: z.number().describe("Northern latitude."),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("circle").describe("Circular search area."),
+      point: GeoPointSchema.describe("Center of the circle."),
+      radiusMeters: z.number().describe("Positive radius in meters."),
+    })
+    .strict(),
+]);
+// Bounds are enforced by the service, after authentication/configuration, so all consumers receive GEO_LIMIT_EXCEEDED.
+export const GeoAutocompleteInputSchema = z
+  .object({
+    text: z.string().describe("Partial address, 3–300 characters."),
+    limit: z.number().optional().describe("At most 5 suggestions; default 5."),
+    countryCode: z.string().optional().describe("Optional ISO alpha-2 country filter."),
+    type: z
+      .enum(["country", "state", "city", "postcode", "street", "amenity", "locality"])
+      .optional()
+      .describe("Optional address result type."),
+    bias: GeoPointSchema.optional().describe("Optional ranking point."),
+    area: GeoAreaSchema.optional().describe("Optional geographic filter."),
+  })
+  .strict();
+export const GeoGeocodeInputSchema = z
+  .object({
+    text: z.string().optional().describe("Address text, at most 300 characters; use text or fields."),
+    fields: z
+      .object({
+        line1: z.string().optional().describe("Street and house number, at most 200 characters."),
+        postalCode: z.string().optional().describe("Postal code, at most 200 characters."),
+        city: z.string().optional().describe("City, at most 200 characters."),
+        stateRegion: z.string().optional().describe("State or region, at most 200 characters."),
+        country: z.string().optional().describe("Country name, at most 200 characters."),
+      })
+      .strict()
+      .optional()
+      .describe("Structured address, at most 200 characters per field."),
+    countryCode: z.string().optional().describe("Optional ISO alpha-2 country filter."),
+  })
+  .strict();
+export const GeoReverseInputSchema = z.object({ point: GeoPointSchema.describe("Coordinates to reverse geocode.") }).strict();
+// 102,400 ASCII bytes matches Geoapify's documented geometry budget, bounding decode memory/work before simplification.
+export const GEO_MAX_POLYLINE_CHARS = 102_400;
+export const GeoPlaceSearchInputSchema = z
+  .object({
+    categories: z.array(GeoCategorySchema).describe("1–5 Cloud categories."),
+    near: GeoPointSchema.optional().describe("Rank by distance to this point; choose near, area, or along."),
+    area: GeoAreaSchema.optional().describe("Optional geographic filter."),
+    along: z
+      .object({
+        polyline6: z.string().describe("Full route as polyline6; at most 102,400 ASCII characters."),
+        fromKm: z.number().describe("Start position on the full route in km."),
+        toKm: z.number().describe("End position; window at most 200 km."),
+        bufferMeters: z.number().optional().describe("100–5,000 m; default 1,000."),
+      })
+      .strict()
+      .optional()
+      .describe("Route corridor with a window of at most 200 km."),
+    limit: z.number().optional().describe("1–20 results; default 20."),
+  })
+  .strict();
+export const GeoPlaceSchema = z
+  .object({
+    id: z.string().min(1).max(2048),
+    name: text,
+    categories: z.array(z.string().max(100)).max(20),
+    point: GeoPointSchema,
+    address: GeoAddressSchema,
+    distanceMeters: z.number().nonnegative().optional(),
+    atMeters: z.number().nonnegative().optional(),
+    distanceToRouteMeters: z.number().nonnegative().optional(),
+    openingHours: z.string().max(1000).optional(),
+    website: z.string().max(1000).optional(),
+    phone: text.optional(),
+    provenance: GeoProvenanceSchema,
+  })
+  .strict();
+export const GeoAutocompleteDataSchema = z
+  .object({ suggestions: z.array(GeoAddressSchema).max(5), provenance: GeoProvenanceSchema })
+  .strict();
+export const GeoGeocodeDataSchema = z.object({ address: GeoAddressSchema, provenance: GeoProvenanceSchema }).strict();
+export const GeoReverseDataSchema = GeoGeocodeDataSchema;
+export const GeoPlaceSearchDataSchema = z
+  .object({
+    places: z.array(GeoPlaceSchema).max(20),
+    provenance: GeoProvenanceSchema,
+    simplificationToleranceMeters: z.number().nonnegative().optional(),
+    truncated: z
+      .boolean()
+      .optional()
+      .describe("Candidate limit reached before filling the requested corridor results; narrow the distance window."),
+  })
+  .strict();
+export const GeoAvailabilityInputSchema = z.object({}).strict();
+const balance = z.object({ exhausted: z.boolean(), resetsAt: z.iso.datetime() }).strict();
+export const GeoAvailabilityDataSchema = z.object({ configured: z.boolean(), person: balance, cloud: balance }).strict();
+export const GeoCostsSchema = z.object({ settledCredits: z.number().nonnegative(), unknownCredits: z.number().nonnegative() }).strict();
+export const GeoErrorDetailsSchema = z.discriminatedUnion("code", [
+  z.object({ code: z.literal("GEO_NOT_CONFIGURED") }).strict(),
+  z.object({ code: z.literal("GEO_FORBIDDEN") }).strict(),
+  z.object({ code: z.literal("GEO_UNSUPPORTED_OPTION") }).strict(),
+  z.object({ code: z.literal("GEO_ADDRESS_NOT_FOUND"), stopId: z.string().optional(), costs: GeoCostsSchema.optional() }).strict(),
+  z.object({ code: z.literal("GEO_NO_ROUTE"), costs: GeoCostsSchema.optional() }).strict(),
+  z
+    .object({
+      code: z.literal("GEO_COST_OVERRUN"),
+      distanceAllowanceMeters: z.number().positive(),
+      actualDistanceMeters: z.number().nonnegative(),
+      costs: GeoCostsSchema,
+    })
+    .strict(),
+  z.object({ code: z.literal("GEO_BUDGET_EXHAUSTED"), scope: z.enum(["person", "cloud"]), resetsAt: z.iso.datetime() }).strict(),
+  z.object({ code: z.literal("GEO_BUSY"), retryAfterSeconds: z.number().positive(), costs: GeoCostsSchema.optional() }).strict(),
+  z
+    .object({
+      code: z.literal("GEO_LIMIT_EXCEEDED"),
+      limit: z.string(),
+      max: z.number(),
+      actual: z.number(),
+      costs: GeoCostsSchema.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      code: z.literal("GEO_ADDRESS_AMBIGUOUS"),
+      stopId: z.string().optional(),
+      costs: GeoCostsSchema.optional(),
+      candidates: z.array(GeoAddressSchema).max(5),
+    })
+    .strict(),
+  z
+    .object({
+      code: z.literal("GEO_PROVIDER_FAILED"),
+      costs: GeoCostsSchema,
+      adminHint: z.string().optional(),
+      accounting: z
+        .object({
+          reservationCredits: z.number().nonnegative(),
+          knownReferenceCredits: z.number().nonnegative(),
+          unknownReferenceCredits: z.number().nonnegative(),
+        })
+        .strict()
+        .optional()
+        .describe("Present when ledger settlement failed: retained reservation and reference costs requiring operator reconciliation."),
+    })
+    .strict(),
+]);
+export type GeoPoint = z.infer<typeof GeoPointSchema>;
+export type GeoProvenance = z.infer<typeof GeoProvenanceSchema>;
+export type GeoAddress = z.infer<typeof GeoAddressSchema>;
+export type GeoPlace = z.infer<typeof GeoPlaceSchema>;
+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 GeoErrorCode = z.infer<typeof GeoErrorDetailsSchema>["code"];
+export type GeoFunction = "autocomplete" | "geocode" | "reverse" | "places" | "route";
+export const geoContract = {
+  autocomplete: { id: "address.autocomplete", input: GeoAutocompleteInputSchema, data: GeoAutocompleteDataSchema },
+  geocode: { id: "address.geocode", input: GeoGeocodeInputSchema, data: GeoGeocodeDataSchema },
+  reverse: { id: "address.reverse", input: GeoReverseInputSchema, data: GeoReverseDataSchema },
+  searchPlaces: { id: "place.search", input: GeoPlaceSearchInputSchema, data: GeoPlaceSearchDataSchema },
+  availability: { id: "geo.availability", input: GeoAvailabilityInputSchema, data: GeoAvailabilityDataSchema },
+} as const;

package/src/contracts/index.ts

@@ -7,6 +7,10 @@ export * from "./capability-compatibility";
 export * from "./commands";
 export * from "./contact-directory";
 export * from "./file-provider";
+export * from "./geo";
+export * from "./geo-admin";
+export * from "./geo-map";
+export * from "./geo-route";
 export * from "./geoip";
 export * from "./notification-types";
 export * from "./outgoing-mail";

package/src/contracts/outgoing-mail.ts

@@ -5,7 +5,9 @@ import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 export const PlatformPermissionSchema = z.enum(["mail:send", "mail:read"]);
 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>;
+export type MailRetention = z.infer<typeof MailRetentionSchema> & {
+  unreadable?: Partial<Record<"outgoing_mail.content_retention_days" | "outgoing_mail.record_retention_days", boolean>>;
+};
 
 export const MailProfileKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
 const headerText = z
@@ -129,6 +131,8 @@ export const AdminMailAppSchema = z.object({
   readDeclared: z.boolean(),
   /** Other apps whose send log this app may read, besides its own. */
   logApps: z.array(z.string()),
+  /** Subset of logApps with explicit content access. Missing on older servers. */
+  logContentApps: z.array(z.string()).optional(),
 });
 export type AdminMailApp = z.infer<typeof AdminMailAppSchema>;
 /** Application IDs as registered, like sender access; Core's own mail is never readable by apps. */
@@ -136,11 +140,15 @@ export const MailLogAppIdSchema = z.string().min(1);
 /** How many other apps' send logs an administrator can let one app read. */
 const MAIL_LOG_GRANT_LIMIT = 100;
 export const MailLogAccessSchema = z
-  .object({ apps: z.array(MailLogAppIdSchema).max(MAIL_LOG_GRANT_LIMIT) })
+  .object({
+    apps: z.array(MailLogAppIdSchema).max(MAIL_LOG_GRANT_LIMIT),
+    contentApps: z.array(MailLogAppIdSchema).max(MAIL_LOG_GRANT_LIMIT).optional(),
+  })
   .strict()
+  .refine((value) => new Set(value.apps).size === value.apps.length && !value.apps.includes("core"), "Choose distinct apps other than core")
   .refine(
-    (value) => new Set(value.apps).size === value.apps.length && !value.apps.includes("core"),
-    "Choose distinct apps other than core",
+    ({ apps, contentApps = [] }) => new Set(contentApps).size === contentApps.length && contentApps.every((id) => apps.includes(id)),
+    "Content apps must be a distinct subset of apps",
   );
 export type MailLogAccess = z.infer<typeof MailLogAccessSchema>;
 
@@ -315,3 +323,8 @@ export type MailServiceError = ServiceError<MailErrorCode> & {
   used?: number;
   requested?: number;
 };
+
+/** One audited read; no HTML, headers, or attachment bytes. */
+export type MailContent = { purged: true; contentPurgedAt: string } | { purged: false; text: string | null; attachmentNames: string[] };
+/** Pass a currently authenticated server context, never browser JSON or a stored actor snapshot. */
+export type MailContentContext = { actor: RequestActor; requestId?: string };

package/src/contracts/registry.ts

@@ -1,4 +1,5 @@
 import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPanel, AppPresentationCatalog, AppSearchLink } from "./app";
+import type { AppAccessRule } from "./app-access";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
 import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
@@ -77,6 +78,7 @@ export type AppRuntimeMetadata = {
 };
 
 export type AppRegistryEntry = {
+  access?: AppAccessRule;
   platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;

package/src/contracts/shared.ts

@@ -206,6 +206,9 @@ export const MessageResponseSchema = z.object({
 });
 export type MessageResponse = z.infer<typeof MessageResponseSchema>;
 
+export const SignOutOthersResponseSchema = MessageResponseSchema.extend({ signInAgain: z.boolean() });
+export type SignOutOthersResponse = z.infer<typeof SignOutOthersResponseSchema>;
+
 export type MutationResult<T = void> = { ok: true; data: T } | { ok: false; error: string; status: 400 | 401 | 403 | 404 | 409 | 500 };
 
 export const PermissionLevelSchema = z.enum(["none", "read", "write", "admin"]);

package/src/events/app-access.ts

@@ -0,0 +1,68 @@
+import type { SQL } from "bun";
+import { z } from "zod";
+import { logger } from "../services/logging";
+import { superviseRuntimeTask } from "../services/runtime-lifecycle";
+import { defineLivePublisher, liveTopic } from "./live-delivery";
+
+const change = z.object({ type: z.literal("app.access.changed"), appId: z.string() });
+// Core already owns and publishes this topic and outbox; no second delivery mechanism.
+const changes = defineLivePublisher({ appId: "core", event: change });
+
+/** Call in the grant/state mutation transaction; rolled-back changes publish nothing. */
+export const publishAppAccessChanged = (tx: SQL, appId: string): Promise<void> =>
+  changes.publish(tx, { key: `app.access:${appId}`, data: { type: "app.access.changed", appId }, access: true });
+export const wakeAppAccessChanged = (): void => changes.wake();
+
+const listeners = new Map<string, Set<() => void>>();
+let active: AbortController | undefined;
+
+/** One follower per process, released as soon as the last live connection ends. */
+export const subscribeAppAccessChanged = (appId: string, changed: () => void): (() => void) => {
+  let callbacks = listeners.get(appId);
+  if (!callbacks) {
+    callbacks = new Set();
+    listeners.set(appId, callbacks);
+  }
+  callbacks.add(changed);
+  if (!active) {
+    const controller = new AbortController();
+    active = controller;
+    const notifyAll = () => {
+      for (const callbacks of listeners.values()) for (const callback of callbacks) callback();
+    };
+    void superviseRuntimeTask({
+      name: "App access invalidations",
+      signal: controller.signal,
+      run: async (signal) => {
+        const source = liveTopic("core");
+        const after = await source.head();
+        if (signal.aborted) return;
+        // Recheck after capturing the cursor to cover changes during subscription startup/reconnect.
+        notifyAll();
+        for await (const event of source.follow({ after, signal })) {
+          const parsed = change.safeParse(event.data.d);
+          if (parsed.success) for (const callback of listeners.get(parsed.data.appId) ?? []) callback();
+        }
+      },
+      onError: ({ error }) => {
+        notifyAll();
+        logger("app-access").warn("App access invalidations failed; reconnecting", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      },
+    }).finally(() => {
+      if (active === controller) active = undefined;
+    });
+  }
+  let subscribed = true;
+  return () => {
+    if (!subscribed) return;
+    subscribed = false;
+    callbacks.delete(changed);
+    if (callbacks.size === 0) listeners.delete(appId);
+    if (listeners.size === 0) {
+      active?.abort();
+      active = undefined;
+    }
+  };
+};