@k2b/cloud 0.45.0 → 0.47.0

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/settings-env.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+export const EnvSettingStatusSchema = z.object({
+  key: z.string(),
+  envVariable: z.string().nullable(),
+  storedValuePresent: z.boolean(),
+  envValuePresent: z.boolean(),
+  conflict: z.enum(["none", "differs", "unknown"]),
+  unreadableStoredValue: z.boolean(),
+  invalidEnvValue: z.boolean(),
+  needsAttention: z.boolean(),
+});
+export const EnvSettingsProcessSchema = z.object({
+  appId: z.string(),
+  instanceId: z.string().optional(),
+  sampledAt: z.number().optional(),
+  status: z.enum(["ok", "unavailable"]),
+  settings: z.array(EnvSettingStatusSchema),
+});
+export const EnvSettingsStatusSchema = z.object({ needsAttention: z.boolean(), processes: z.array(EnvSettingsProcessSchema) });
+export type EnvSettingStatus = z.infer<typeof EnvSettingStatusSchema>;

package/src/contracts/settings-types.ts

@@ -36,6 +36,12 @@ type CommonDef = {
   presentation?: AppSettingPresentation;
   envBootstrap?: EnvResolver;
   envFallback?: EnvResolver;
+  /** Environment name for migration diagnostics; values are never returned. */
+  envVariable?: string;
+  /** Discard these stored settings when this normalized value changes. */
+  resetOnChange?: readonly string[];
+  /** Additional server-side validation after kind normalization. */
+  validate?: (value: unknown) => string | undefined;
 };
 
 type StringLikeKind = "string" | "text" | "email" | "url" | "secret" | "image" | "cron" | "timezone" | "template";

package/src/geo/AddressAutocomplete.tsx

@@ -0,0 +1,213 @@
+import { Combobox, type ComboboxOption, type FieldProps, TextInput, useLocale } from "@k2b/ui";
+import { createSignal, type JSX, onCleanup, onMount, Show } from "solid-js";
+import { invokeCapabilityWithDataSchema } from "../capabilities/client";
+import { type GeoAddress, type GeoAvailabilityData, geoContract } from "../contracts/geo";
+import { geoUiMessages } from "./messages";
+
+type Budget = { scope: "person" | "cloud"; resetsAt: string };
+
+export type AddressAutocompleteProps = Omit<FieldProps, "label"> & {
+  label: JSX.Element;
+  /** The street line as typed; the person's own text always stays possible. */
+  value: string;
+  onValueChange: (value: string) => void;
+  /** A chosen suggestion. The host fills its fields from it and keeps point and provenance. */
+  onPick: (address: GeoAddress) => void;
+  /** The person keeps the typed text instead of a suggestion. */
+  onOwnEntry?: (value: string) => void;
+  /** From the SSR snapshot. Without a configured geo service the field is a plain text input. */
+  availability?: GeoAvailabilityData;
+  placeholder?: string;
+  /** Icon of the plain text input when suggestions are off. */
+  icon?: string;
+};
+
+/** Suggestions cost a credit each: 3–300 characters, 250 ms pause, at most 5, one request per field in flight. */
+const MIN_TEXT = 3;
+const MAX_TEXT = 300;
+const LIMIT = 5;
+const DEBOUNCE_MS = 250;
+const OWN = "own";
+
+// The list only opens in the browser, so the browser's zone is the reader's zone here.
+const budgetText = (budget: Budget, locale: string, t: ReturnType<typeof geoUiMessages.resolve>["t"]) => {
+  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const at = new Date(budget.resetsAt);
+  return budget.scope === "person"
+    ? t.budgetPerson({ time: new Intl.DateTimeFormat(locale, { hour: "numeric", minute: "2-digit", timeZone }).format(at) })
+    : t.budgetCloud({ date: new Intl.DateTimeFormat(locale, { day: "numeric", month: "long", timeZone }).format(at) });
+};
+
+/** Address field with Cloud's budgeted suggestions; picking fills nothing by itself, the host owns its fields. */
+export function AddressAutocomplete(props: AddressAutocompleteProps): JSX.Element {
+  const locale = useLocale();
+  const t = () => geoUiMessages.resolve([locale()]).t;
+  const initialBudget = (): Budget | null => {
+    const value = props.availability;
+    if (value?.person.exhausted) return { scope: "person", ...value.person };
+    if (value?.cloud.exhausted) return { scope: "cloud", ...value.cloud };
+    return null;
+  };
+  const [budget, setBudget] = createSignal<Budget | null>(initialBudget());
+  const [phone, setPhone] = createSignal(false);
+  // The budget line names a time in the reader's browser zone; it exists only once the list can open.
+  const [mounted, setMounted] = createSignal(false);
+  onMount(() => {
+    setMounted(true);
+    const query = window.matchMedia("(max-width: 639px)");
+    const update = () => setPhone(query.matches);
+    update();
+    query.addEventListener("change", update);
+    onCleanup(() => query.removeEventListener("change", update));
+  });
+
+  // Options carry the id of the answer they came from, so a pick always resolves to the address it showed.
+  let suggestions = new Map<string, GeoAddress>();
+  let responses = 0;
+  // The keyboard hint belongs to a list of choices, not to an empty, failed, or budget answer.
+  const [choices, setChoices] = createSignal(false);
+  let inflight: Promise<unknown> | undefined;
+  const ownOption = (text: string): ComboboxOption => ({
+    id: OWN,
+    label: t().ownEntry({ text: text.trim() }),
+    description: t().ownEntryDetail,
+    icon: "ti ti-keyboard",
+  });
+  const withOwn = (text: string, options: ComboboxOption[]) => (phone() ? [ownOption(text), ...options] : [...options, ownOption(text)]);
+
+  const countryName = (code: string) => {
+    if (!code) return "";
+    try {
+      return new Intl.DisplayNames([locale()], { type: "region" }).of(code) ?? code;
+    } catch {
+      return code;
+    }
+  };
+
+  const fetchData = async (text: string, signal: AbortSignal): Promise<ComboboxOption[]> => {
+    if (text.trim().length > MAX_TEXT) return withOwn(text, []);
+    // A newer query waits for the open request instead of cancelling a call Core may already have paid for.
+    while (inflight) await inflight.catch(() => {});
+    signal.throwIfAborted();
+    const request = invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.autocomplete.id, input: { text, limit: LIMIT } },
+      geoContract.autocomplete.data,
+    );
+    inflight = request;
+    const result = await request.finally(() => {
+      if (inflight === request) inflight = undefined;
+    });
+    // A superseded answer never touches the state behind the options a newer answer shows.
+    signal.throwIfAborted();
+    setChoices(result.ok && result.data.data.suggestions.length > 0);
+    if (!result.ok) {
+      const details = result.error.details;
+      if (
+        result.error.code === "GEO_BUDGET_EXHAUSTED" &&
+        (details?.scope === "person" || details?.scope === "cloud") &&
+        typeof details.resetsAt === "string"
+      ) {
+        setBudget({ scope: details.scope, resetsAt: details.resetsAt });
+        return [];
+      }
+      throw new Error(t().unavailable);
+    }
+    responses += 1;
+    const answer = responses;
+    const found = result.data.data.suggestions.slice(0, LIMIT);
+    suggestions = new Map(found.map((address, index) => [`${answer}:${index}`, address]));
+    if (!found.length) return [];
+    return withOwn(
+      text,
+      found.map((address, index) => ({
+        id: `${answer}:${index}`,
+        label: address.line1 || address.formatted,
+        description: [[address.postalCode, address.city].filter(Boolean).join(" "), countryName(address.countryCode)]
+          .filter(Boolean)
+          .join(", "),
+        icon: "ti ti-map-pin",
+      })),
+    );
+  };
+
+  const budgetStatus = () => {
+    const value = budget();
+    if (!value) return undefined;
+    return (
+      <span class="flex items-start gap-2">
+        <i class="ti ti-hourglass" aria-hidden="true" />
+        <span>
+          <strong class="block font-medium">{budgetText(value, locale(), t())}</strong>
+          {t().budgetDetail}
+        </span>
+      </span>
+    );
+  };
+
+  return (
+    <Show
+      when={props.availability?.configured !== false}
+      fallback={
+        <TextInput
+          id={props.id}
+          class={props.class}
+          label={props.label}
+          description={props.description}
+          error={props.error}
+          required={props.required}
+          disabled={props.disabled}
+          placeholder={props.placeholder}
+          icon={props.icon}
+          value={() => props.value}
+          onValueChange={props.onValueChange}
+        />
+      }
+    >
+      <Combobox
+        id={props.id}
+        class={props.class}
+        label={props.label}
+        description={props.description}
+        error={props.error}
+        required={props.required}
+        disabled={props.disabled}
+        aria-label={props["aria-label"]}
+        aria-describedby={props["aria-describedby"]}
+        placeholder={props.placeholder}
+        freeText
+        autoHighlight={phone() ? 1 : 0}
+        minQueryLength={MIN_TEXT}
+        debounceMs={DEBOUNCE_MS}
+        query={() => props.value}
+        onQueryChange={props.onValueChange}
+        status={mounted() ? budgetStatus() : undefined}
+        empty={
+          <span>
+            <strong class="block font-medium">{t().noMatch}</strong>
+            {t().noMatchDetail}
+          </span>
+        }
+        footer={
+          <>
+            <span>{phone() || budget() || !choices() ? "" : t().keyboardHint}</span>
+            <span>
+              <a href="https://www.geoapify.com/" target="_blank" rel="noopener noreferrer">
+                Geoapify
+              </a>
+              {" · "}
+              <a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener noreferrer">
+                OpenStreetMap
+              </a>
+            </span>
+          </>
+        }
+        fetchData={fetchData}
+        onSelect={(option) => {
+          if (option.id === OWN) return props.onOwnEntry?.(props.value);
+          const address = suggestions.get(option.id);
+          if (address) props.onPick(address);
+        }}
+      />
+    </Show>
+  );
+}

package/src/geo/messages.ts

@@ -0,0 +1,29 @@
+import { i18n } from "@k2b/stdlib";
+
+export const geoUiMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      ownEntry: ({ text }: { text: string }) => `Use “${text}” as typed`,
+      ownEntryDetail: "You fill in street, postal code, and city yourself",
+      noMatch: "No matching address found.",
+      noMatchDetail: "Enter it yourself. It is saved exactly as you write it.",
+      unavailable: "Suggestions are unavailable right now. You can enter the address yourself.",
+      budgetPerson: ({ time }: { time: string }) => `Suggestions are used up for today, back at ${time}.`,
+      budgetCloud: ({ date }: { date: string }) => `Suggestions are used up until ${date}.`,
+      budgetDetail: "You can enter the address yourself.",
+      keyboardHint: "↑↓ choose · Enter accepts",
+    },
+    de: {
+      ownEntry: ({ text }) => `„${text}“ so übernehmen`,
+      ownEntryDetail: "Straße, PLZ und Ort trägst du selbst ein",
+      noMatch: "Keine passende Adresse gefunden.",
+      noMatchDetail: "Trag sie selbst ein. Sie wird so gespeichert, wie du sie schreibst.",
+      unavailable: "Vorschläge gerade nicht verfügbar. Du kannst die Adresse selbst eintragen.",
+      budgetPerson: ({ time }) => `Vorschläge heute aufgebraucht, ab ${time} Uhr wieder.`,
+      budgetCloud: ({ date }) => `Vorschläge bis ${date} aufgebraucht.`,
+      budgetDetail: "Du kannst die Adresse selbst eintragen.",
+      keyboardHint: "↑↓ wählen · Enter übernehmen",
+    },
+  },
+});

package/src/geo/navigation.ts

@@ -0,0 +1,25 @@
+import type { GeoPoint } from "../contracts/geo";
+
+export type GeoNavigationPlatform = "android" | "ios" | "desktop";
+
+/** Phones open their own maps app; everything else gets OpenStreetMap. */
+export const geoNavigationPlatform = (userAgent: string): GeoNavigationPlatform =>
+  /android/i.test(userAgent) ? "android" : /iphone|ipad|ipod/i.test(userAgent) ? "ios" : "desktop";
+
+/**
+ * A link into a navigation app. Cloud does no live navigation; the link leaves Cloud only on click and carries
+ * just the destination and an optional name. Without a point it navigates to the address text.
+ */
+export const geoNavigationHref = (
+  target: { point?: GeoPoint | null; text: string; name?: string },
+  platform: GeoNavigationPlatform,
+): string => {
+  const point = target.point ? `${target.point.lat},${target.point.lon}` : null;
+  const text = encodeURIComponent(target.text);
+  if (platform === "android")
+    return point ? `geo:0,0?q=${point}${target.name ? `(${encodeURIComponent(target.name)})` : ""}` : `geo:0,0?q=${text}`;
+  if (platform === "ios") return `https://maps.apple.com/?daddr=${point ? encodeURIComponent(point) : text}`;
+  return point
+    ? `https://www.openstreetmap.org/directions?route=%3B${encodeURIComponent(point)}`
+    : `https://www.openstreetmap.org/search?query=${text}`;
+};

package/src/geo/ui.ts

@@ -1 +1,3 @@
+export { AddressAutocomplete, type AddressAutocompleteProps } from "./AddressAutocomplete";
 export { CloudMap, CloudMapAttribution, type CloudMapProps } from "./CloudMap";
+export { type GeoNavigationPlatform, geoNavigationHref, geoNavigationPlatform } from "./navigation";

package/src/index.ts

@@ -60,5 +60,14 @@ export type {
   NotificationSendInput,
 } from "./contracts/notification-types";
 export { notification } from "./contracts/notification-types";
+export { createRedis, createSql, redis, type SqlPoolOptions, sql } from "./runtime/clients";
+export {
+  type ConnectionSource,
+  connections,
+  type PlatformConnectionSources,
+  type PlatformConnections,
+  type PlatformConnectionValues,
+} from "./runtime/connections";
 export type { HelpDefinition, HelpDefinitionDocument } from "./server/help";
 export { defineHelp } from "./server/help";
+export { storage } from "./services/object-store";

package/src/runtime/clients.ts

@@ -0,0 +1,72 @@
+import { RedisClient, type RedisOptions, SQL } from "bun";
+import { postgresApplicationOptions } from "../_internal/postgres-application-name";
+import { connections, hasConnections } from "./connections";
+
+export type SqlPoolOptions = SQL.PostgresOrMySQLOptions;
+
+/** Only the pre-start placeholder is proxied; initialized clients are native Bun objects. */
+const notStarted = <T>(name: string): T => {
+  const fail = (): never => {
+    throw new Error(`${name} used before platform start`);
+  };
+  return new Proxy(fail, {
+    get: fail,
+    set: fail,
+    apply: fail,
+    construct: fail,
+    getPrototypeOf: fail,
+    defineProperty: fail,
+    deleteProperty: fail,
+    has: fail,
+    ownKeys: fail,
+    getOwnPropertyDescriptor: fail,
+    setPrototypeOf: fail,
+    isExtensible: fail,
+    preventExtensions: fail,
+  }) as T;
+};
+
+export let sql: SQL = notStarted("sql");
+export let redis: RedisClient = notStarted("redis");
+
+/** Own pool and lifecycle; defaults to the installation URL and application name. */
+export const createSql = (options: SqlPoolOptions = {}): SQL => {
+  const state = connections();
+  const url = options.url ?? state.database.url;
+  const connection = { ...postgresApplicationOptions(state.appId, url.toString()), ...options.connection };
+  return new SQL({
+    ...options,
+    url,
+    ...(Object.keys(connection).length ? { connection } : {}),
+  });
+};
+
+/** Own connection and lifecycle, using the installation's Valkey URL. */
+export const createRedis = (options?: RedisOptions): RedisClient => new RedisClient(connections().valkey.url, options);
+
+export const initializeClients = async (): Promise<void> => {
+  let database: SQL;
+  try {
+    database = createSql();
+  } catch {
+    throw new Error("Postgres client configuration is invalid; check DATABASE_URL and native SQL options");
+  }
+  try {
+    const valkey = createRedis();
+    sql = database;
+    redis = valkey;
+  } catch {
+    await database.close();
+    throw new Error("Valkey client configuration is invalid; check REDIS_URL and native Redis options");
+  }
+};
+
+/** Internal test-target teardown, before a fixture selects a different database. */
+export const closePlatformClients = async (): Promise<void> => {
+  if (hasConnections()) {
+    await sql.close();
+    redis.close();
+  }
+  sql = notStarted("sql");
+  redis = notStarted("redis");
+};

package/src/runtime/connections.ts

@@ -0,0 +1,37 @@
+/** Startup snapshot. Connection credentials never flow back into the process environment. */
+export type ConnectionSource = "env" | "core";
+export type PlatformConnectionValues = {
+  database: { url: string };
+  valkey: { url: string };
+  nats: {
+    servers: string[];
+    namespace: string;
+    replicas: 1 | 3 | 5;
+    ignoreClusterUpdates: boolean;
+    /** Mounted credentials and CA files are read once; these are contents, not paths. */
+    creds?: string;
+    ca?: string;
+  };
+  appSecret: { current: string; previous?: string; next?: string };
+};
+export type PlatformConnectionSources = {
+  [Group in keyof PlatformConnectionValues]: { [Key in keyof PlatformConnectionValues[Group]]: ConnectionSource };
+};
+export type PlatformConnections = PlatformConnectionValues & {
+  appId: string;
+  sources: PlatformConnectionSources;
+};
+
+let current: PlatformConnections | undefined;
+
+export const connections = (): PlatformConnections => {
+  if (!current)
+    throw new Error("connections() used before platform start; use @k2b/cloud/start, the Cloud build entry or development preload");
+  return current;
+};
+
+/** Internal startup binding; tests replace it only after closing their previous clients. */
+export const bindConnections = (value: PlatformConnections | undefined): void => {
+  current = value;
+};
+export const hasConnections = (): boolean => current !== undefined;