Add the account area and account-synced Appearance preferences

Stage 1 PR 6 (ADR 0062). /account shows who is signed in; /account/appearance
chooses System, Light, or Dark and reduced motion (System, Reduce, Allow).

- Core: ekklesia_core_user_preference, one typed, CHECK-constrained,
  nullable column per preference (null = never chosen), migration
  0008_user_preferences (additive), @ekklesia/core/account store, and the
  authenticated-baseline permission core.account.self.manage.
- API: GET /api/v1/account (name, email, preferences) and partial
  PATCH /api/v1/account/preferences, self-only by construction: no user id
  is accepted anywhere; trusted Origin and body limit on the mutation.
- Shell: the account control shows name, email, and initials (never the
  unvetted image URL) and offers Account, Appearance, Sign out; native
  radio groups apply a choice at once through the ADR 0060 controller and
  save it; the server's answer wins and a failed save reverts.
- First paint: a classic, same-origin, render-blocking appearance.js in
  <head> applies a two-word localStorage cache before paint (no inline
  script, CSP unchanged). The account replaces the cache on every load,
  sign-out clears it, and other tabs follow via the storage event.
- Deploy smoke: real-Chromium checks for light/dark, OS emulation,
  overrides, reload persistence, pre-paint, Shadow DOM modules, reduced
  motion, the display staying light, and phone width; the browser
  container gets a 512 MiB /dev/shm so a long session no longer fails
  requests with ERR_INSUFFICIENT_RESOURCES.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

core/src/account/database.ts

@@ -0,0 +1,13 @@
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { Pool } from "pg";
+import { accountSchema } from "./schema.js";
+
+export type AccountDrizzleDatabase = NodePgDatabase<typeof accountSchema>;
+
+/**
+ * A typed Drizzle view over an externally owned pool, exactly like `createDeviceDrizzleView`: it
+ * never constructs, registers an error listener on, or closes a pool.
+ */
+export function createAccountDrizzleView(pool: Pool): AccountDrizzleDatabase {
+  return drizzle(pool, { schema: accountSchema });
+}

core/src/account/index.ts

@@ -0,0 +1,4 @@
+export * from "./database.js";
+export * from "./preferences.js";
+export * from "./schema.js";
+export * from "./store.js";

core/src/account/preferences.ts

@@ -0,0 +1,108 @@
+/**
+ * A person's own preferences (DESIGN.md §9.2, ADR 0062): how the Dashboard looks and behaves *for
+ * them*, on every device they sign in on.
+ *
+ * The model is deliberately a closed, typed record rather than a key/value bag or a JSON document.
+ * Every preference has a fixed name, a closed set of values, and a default; a value outside the set
+ * is refused at this boundary and again by the database's `CHECK` constraint. A new preference is a
+ * new field here and a new nullable column in a migration — never a second table, and never a
+ * free-form value a client could fill with anything.
+ *
+ * Core cannot import the design-token package that renders these, so the value sets are declared
+ * here and an `apps/api` test holds them equal to `@ekklesia/design-tokens`' own
+ * (`EKKLESIA_APPEARANCES`, `EKKLESIA_MOTION_PREFERENCES`): one list cannot change without the other.
+ */
+
+/** Light, dark, or following the operating system. `system` is the default. */
+export const ACCOUNT_APPEARANCES = Object.freeze(["system", "light", "dark"] as const);
+export type AccountAppearance = (typeof ACCOUNT_APPEARANCES)[number];
+
+/** Following `prefers-reduced-motion`, always reducing, or always allowing the platform's subtle
+ * motion. `system` is the default. */
+export const ACCOUNT_MOTION_PREFERENCES = Object.freeze(["system", "reduce", "allow"] as const);
+export type AccountMotionPreference = (typeof ACCOUNT_MOTION_PREFERENCES)[number];
+
+export interface AccountPreferences {
+  readonly appearance: AccountAppearance;
+  readonly motion: AccountMotionPreference;
+}
+
+/** What a person who has never chosen anything gets: follow the system for both. */
+export const DEFAULT_ACCOUNT_PREFERENCES: AccountPreferences = Object.freeze({
+  appearance: "system",
+  motion: "system",
+});
+
+/** A change to some of a person's preferences. Fields left out keep their stored value, so
+ * changing motion on a phone never overwrites an appearance chosen a moment earlier on a laptop. */
+export type AccountPreferencesUpdate = Partial<AccountPreferences>;
+
+const PREFERENCE_VALUES: Readonly<Record<keyof AccountPreferences, readonly string[]>> =
+  Object.freeze({
+    appearance: ACCOUNT_APPEARANCES,
+    motion: ACCOUNT_MOTION_PREFERENCES,
+  });
+
+/** The preference names, in a stable order. */
+export const ACCOUNT_PREFERENCE_NAMES = Object.freeze(
+  Object.keys(PREFERENCE_VALUES).sort() as (keyof AccountPreferences)[],
+);
+
+export function isAccountAppearance(value: unknown): value is AccountAppearance {
+  return typeof value === "string" && ACCOUNT_APPEARANCES.includes(value as AccountAppearance);
+}
+
+export function isAccountMotionPreference(value: unknown): value is AccountMotionPreference {
+  return (
+    typeof value === "string" &&
+    ACCOUNT_MOTION_PREFERENCES.includes(value as AccountMotionPreference)
+  );
+}
+
+/**
+ * Reads an untrusted update strictly: a plain object naming at least one known preference, each
+ * with one of its allowed values, and nothing else. Returns `undefined` for anything else — an
+ * unknown key, a wrong value, an empty object, an array, `null` — so a malformed request is refused
+ * whole rather than partly applied, and no unexpected key can ever reach storage.
+ */
+export function parseAccountPreferencesUpdate(
+  value: unknown,
+): AccountPreferencesUpdate | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) {
+    return undefined;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return undefined;
+  }
+  const update: { appearance?: AccountAppearance; motion?: AccountMotionPreference } = {};
+  for (const [key, entry] of entries) {
+    if (key === "appearance" && isAccountAppearance(entry)) {
+      update.appearance = entry;
+    } else if (key === "motion" && isAccountMotionPreference(entry)) {
+      update.motion = entry;
+    } else {
+      return undefined;
+    }
+  }
+  return Object.freeze(update);
+}
+
+/** Resolves stored columns, where `null` means "never chosen", to the preferences in effect. A
+ * stored value the database constraint should have made impossible is treated as never chosen. */
+export function resolveAccountPreferences(stored: {
+  readonly appearance: string | null;
+  readonly motion: string | null;
+}): AccountPreferences {
+  return Object.freeze({
+    appearance: isAccountAppearance(stored.appearance)
+      ? stored.appearance
+      : DEFAULT_ACCOUNT_PREFERENCES.appearance,
+    motion: isAccountMotionPreference(stored.motion)
+      ? stored.motion
+      : DEFAULT_ACCOUNT_PREFERENCES.motion,
+  });
+}

core/src/account/schema.ts

@@ -0,0 +1,56 @@
+import { sql } from "drizzle-orm";
+import { check, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+import { ekklesiaCoreUser } from "../identity/schema.js";
+
+/**
+ * Core-owned storage for a person's own preferences (ADR 0062).
+ *
+ * **One row per person, one typed column per preference.** There is deliberately no key/value
+ * table and no JSON column: each preference has a fixed name and a closed set of values, enforced
+ * here by a `CHECK` constraint beneath the application-layer parser
+ * (`parseAccountPreferencesUpdate`), so nothing but a known value can be stored. A new preference is
+ * a new nullable column in a new migration.
+ *
+ * **`null` means "never chosen"**, and is resolved to the platform default when read
+ * (`resolveAccountPreferences`) rather than written as a column default. That keeps "this person
+ * chose System" distinguishable from "this person never chose", and lets a later preference column
+ * arrive without backfilling a value nobody chose — the same reasoning
+ * `ekklesia_core_module_state` follows for its absent rows (ADR 0028). A person with no row at all
+ * has chosen nothing.
+ *
+ * The row belongs to its person: `user_id` is the primary key and cascades on delete, so deleting
+ * an account removes its preferences with it, and no row can exist for a person who does not.
+ *
+ * Personal, not church-wide. Nothing here is branding, a church theme, or an administrator's
+ * decision for anyone else; those are Settings' (ADR 0061).
+ */
+export const ekklesiaCoreUserPreference = pgTable(
+  "ekklesia_core_user_preference",
+  {
+    userId: text("user_id")
+      .primaryKey()
+      .references(() => ekklesiaCoreUser.id, { onDelete: "cascade" }),
+    appearance: text("appearance"),
+    motion: text("motion"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+  },
+  (table) => [
+    check(
+      "ekklesia_core_user_preference_appearance_check",
+      sql`${table.appearance} is null or ${table.appearance} in ('system', 'light', 'dark')`,
+    ),
+    check(
+      "ekklesia_core_user_preference_motion_check",
+      sql`${table.motion} is null or ${table.motion} in ('system', 'reduce', 'allow')`,
+    ),
+  ],
+);
+
+/** Explicit map passed to Drizzle, mirroring `dashboardSchema` and `moduleLifecycleSchema`. The
+ * user table is included because the account summary reads a person's own name and email from it;
+ * nothing in this domain writes to it. */
+export const accountSchema = {
+  user: ekklesiaCoreUser,
+  userPreference: ekklesiaCoreUserPreference,
+} as const;

core/src/account/store.ts

@@ -0,0 +1,156 @@
+import type { EkklesiaUserId } from "@ekklesia/contracts";
+import { eq, sql } from "drizzle-orm";
+import { ekklesiaCoreUser } from "../identity/schema.js";
+import type { AccountDrizzleDatabase } from "./database.js";
+import {
+  type AccountPreferences,
+  type AccountPreferencesUpdate,
+  parseAccountPreferencesUpdate,
+  resolveAccountPreferences,
+} from "./preferences.js";
+import { ekklesiaCoreUserPreference } from "./schema.js";
+
+export type AccountStoreErrorCode =
+  | "ACCOUNT_NOT_FOUND"
+  | "ACCOUNT_PREFERENCES_INVALID"
+  | "ACCOUNT_READ_FAILED"
+  | "ACCOUNT_WRITE_FAILED";
+
+const accountStoreMessages: Readonly<Record<AccountStoreErrorCode, string>> = Object.freeze({
+  ACCOUNT_NOT_FOUND: "The account was not found.",
+  ACCOUNT_PREFERENCES_INVALID: "The preferences are not valid.",
+  ACCOUNT_READ_FAILED: "The account could not be read.",
+  ACCOUNT_WRITE_FAILED: "The preferences could not be saved.",
+});
+
+/** Never carries the underlying database error, SQL text, host, or stack — matching
+ * `DashboardStoreError` exactly. */
+export class AccountStoreError extends Error {
+  readonly code: AccountStoreErrorCode;
+
+  constructor(code: AccountStoreErrorCode) {
+    super(accountStoreMessages[code]);
+    this.name = "AccountStoreError";
+    this.code = code;
+    this.stack = `${this.name}: ${this.message}`;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * What a signed-in person is shown about their own account: the name and email they signed up
+ * with, and their preferences. Deliberately nothing else — not the image URL, not verification
+ * state, not timestamps — so the one place the browser learns about an account carries exactly
+ * what the account area displays (ADR 0062).
+ */
+export interface AccountSummary {
+  readonly name: string;
+  readonly email: string;
+  readonly preferences: AccountPreferences;
+}
+
+/**
+ * A person's own account, and only their own: every method takes the one user id whose account it
+ * reads or writes, and the HTTP surface supplies it from the authenticated session, never from the
+ * request. There is no method that lists accounts or reads someone else's by any other key.
+ */
+export interface AccountStore {
+  /** The person's summary, or `undefined` when no such person exists. A person who never chose a
+   * preference gets the defaults. */
+  readAccount(userId: EkklesiaUserId): Promise<AccountSummary | undefined>;
+  /** Changes the named preferences and keeps the rest, returning everything now in effect. */
+  updatePreferences(
+    userId: EkklesiaUserId,
+    update: AccountPreferencesUpdate,
+  ): Promise<AccountPreferences>;
+}
+
+function rethrowAsStoreError(error: unknown, code: AccountStoreErrorCode): never {
+  if (error instanceof AccountStoreError) {
+    throw error;
+  }
+  throw new AccountStoreError(code);
+}
+
+/**
+ * Core's persistence for a person's own account summary and preferences.
+ *
+ * Validation lives here as well as at the HTTP boundary, so the invariants hold for any caller: an
+ * update is re-read through the same strict parser, and a preference row can only be written for a
+ * person who exists.
+ */
+export function createAccountStore(db: AccountDrizzleDatabase): AccountStore {
+  return Object.freeze({
+    async readAccount(userId: EkklesiaUserId): Promise<AccountSummary | undefined> {
+      try {
+        const rows = await db
+          .select({
+            appearance: ekklesiaCoreUserPreference.appearance,
+            email: ekklesiaCoreUser.email,
+            motion: ekklesiaCoreUserPreference.motion,
+            name: ekklesiaCoreUser.name,
+          })
+          .from(ekklesiaCoreUser)
+          .leftJoin(
+            ekklesiaCoreUserPreference,
+            eq(ekklesiaCoreUserPreference.userId, ekklesiaCoreUser.id),
+          )
+          .where(eq(ekklesiaCoreUser.id, userId))
+          .limit(1);
+        const row = rows[0];
+        if (!row) {
+          return undefined;
+        }
+        return Object.freeze({
+          email: row.email,
+          name: row.name,
+          preferences: resolveAccountPreferences(row),
+        });
+      } catch (error) {
+        rethrowAsStoreError(error, "ACCOUNT_READ_FAILED");
+      }
+    },
+
+    async updatePreferences(
+      userId: EkklesiaUserId,
+      update: AccountPreferencesUpdate,
+    ): Promise<AccountPreferences> {
+      const parsed = parseAccountPreferencesUpdate(update);
+      if (parsed === undefined) {
+        throw new AccountStoreError("ACCOUNT_PREFERENCES_INVALID");
+      }
+      try {
+        return await db.transaction(async (tx) => {
+          // Checked inside the transaction rather than left to the foreign key, so a person who
+          // does not exist is a clear "not found" instead of a constraint failure.
+          const people = await tx
+            .select({ id: ekklesiaCoreUser.id })
+            .from(ekklesiaCoreUser)
+            .where(eq(ekklesiaCoreUser.id, userId))
+            .limit(1);
+          if (people.length === 0) {
+            throw new AccountStoreError("ACCOUNT_NOT_FOUND");
+          }
+          const rows = await tx
+            .insert(ekklesiaCoreUserPreference)
+            .values({ userId, ...parsed })
+            .onConflictDoUpdate({
+              set: { ...parsed, updatedAt: sql`now()` },
+              target: ekklesiaCoreUserPreference.userId,
+            })
+            .returning({
+              appearance: ekklesiaCoreUserPreference.appearance,
+              motion: ekklesiaCoreUserPreference.motion,
+            });
+          const row = rows[0];
+          if (!row) {
+            throw new AccountStoreError("ACCOUNT_WRITE_FAILED");
+          }
+          return resolveAccountPreferences(row);
+        });
+      } catch (error) {
+        rethrowAsStoreError(error, "ACCOUNT_WRITE_FAILED");
+      }
+    },
+  });
+}