create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/src/core/http/respond.ts

@@ -0,0 +1,82 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// The one translation from a ServiceError into an HTTP status. Doing this once,
+// here, is what stops each route inventing its own status codes and its own
+// idea of how much to tell the caller.
+import { ServiceError, type Actor } from "@/core/service";
+import { RequestBodyError } from "@/core/http/body";
+
+const STATUS: Record<ServiceError["code"], number> = {
+  validation: 400,
+  permission: 403,
+  not_found: 404,
+  conflict: 409,
+  rate_limited: 429,
+  step_up_required: 403,
+  internal: 500,
+};
+
+export interface ResponseParts {
+  headers?: Record<string, string>;
+  /**
+   * Set-Cookie is the one header that legitimately repeats, and a plain record
+   * cannot express that — signing in sets both the session and CSRF cookies.
+   */
+  cookies?: string[];
+}
+
+export function json(
+  body: unknown,
+  status = 200,
+  parts: ResponseParts = {},
+): Response {
+  const headers = new Headers({
+    "content-type": "application/json; charset=utf-8",
+    ...parts.headers,
+  });
+  for (const cookie of parts.cookies ?? []) {
+    headers.append("set-cookie", cookie);
+  }
+  return new Response(JSON.stringify(body), { status, headers });
+}
+
+/**
+ * ServiceError messages are written for the caller and are safe to return —
+ * they say what was wrong with the request, never how the system works.
+ * Anything else is a bug, and a bug's message can contain a connection string
+ * or a query, so it is logged and answered with a flat 500.
+ *
+ * A refused permission answers 401 for an anonymous caller and 403 for a
+ * signed-in one: the first means "log in", the second means "logging in as
+ * someone else would not help", and conflating them makes both confusing.
+ */
+export function errorResponse(error: unknown, actor: Actor): Response {
+  if (error instanceof RequestBodyError) {
+    return json(
+      { error: { code: "validation", message: error.message } },
+      error.status,
+    );
+  }
+  if (error instanceof ServiceError) {
+    const status =
+      error.code === "permission" && actor.kind === "anonymous"
+        ? 401
+        : STATUS[error.code];
+    // Retry-After turns "try later" into a number the caller can act on —
+    // clients and well-behaved crawlers both honour it, and a person staring
+    // at a login form deserves to be told how long rather than guessing.
+    const headers = error.retryAfterSeconds
+      ? { "retry-after": String(error.retryAfterSeconds) }
+      : undefined;
+    return json(
+      { error: { code: error.code, message: error.message } },
+      status,
+      { headers },
+    );
+  }
+  console.error("unhandled error in a route handler", error);
+  return json(
+    { error: { code: "internal", message: "Something went wrong." } },
+    500,
+  );
+}

package/dist/template/src/core/http/route.ts

@@ -0,0 +1,83 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Routes are thin wrappers over services (MASTER.md §10, §15.5) — and "thin"
+// is only true if the wrapping is written once. serviceRoute is that once: it
+// resolves the actor, reads the input, calls the service, and maps failures to
+// status codes. A handler that needs more than `present` to shape its response
+// is a sign the work belongs in a service.
+//
+// Framework-agnostic on purpose (web Request/Response, no next/* imports), so
+// app/ stays a routing skin over an application that does not know about it.
+import type { z } from "zod";
+import { actorFromRequest } from "@/core/http/actor";
+import { requireCsrf } from "@/core/http/csrf";
+import { errorResponse, json, type ResponseParts } from "@/core/http/respond";
+import type { Service } from "@/core/service";
+import { DEFAULT_JSON_BODY_LIMIT, readBoundedText } from "@/core/http/body";
+
+export interface Presented extends ResponseParts {
+  status?: number;
+  body?: unknown;
+}
+
+export interface ServiceRouteOptions<Out> {
+  /**
+   * Where the input comes from. Defaults to the JSON body, or the query string
+   * for GET. Routes whose input is a credential the browser holds — a session
+   * token in a cookie — override this so the value is never accepted from a
+   * caller-supplied body.
+   */
+  readInput?: (request: Request) => unknown;
+  /**
+   * Shape the success response. This is where a session token becomes a
+   * Set-Cookie header instead of a field in the body.
+   */
+  present?: (result: Out) => Presented;
+}
+
+async function readJsonBody(request: Request): Promise<unknown> {
+  const text = await readBoundedText(request, DEFAULT_JSON_BODY_LIMIT);
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    // A malformed body is the caller's mistake, and the service's Zod parse
+    // will say so in the same shape as every other bad request.
+    return {};
+  }
+}
+
+function readQuery(request: Request): unknown {
+  return Object.fromEntries(new URL(request.url).searchParams);
+}
+
+export function serviceRoute<In extends z.ZodType, Out>(
+  service: Service<In, Out>,
+  options: ServiceRouteOptions<Out> = {},
+): (request: Request) => Promise<Response> {
+  return async function handler(request: Request): Promise<Response> {
+    // Resolved before anything else, because it decides both what the service
+    // will allow and whether a refusal reads as 401 or 403.
+    const actor = await actorFromRequest(request);
+    try {
+      // Before the service, and before the body is even parsed: a forged
+      // request must not reach business logic at all.
+      requireCsrf(request);
+
+      const input = options.readInput
+        ? await options.readInput(request)
+        : request.method === "GET"
+          ? readQuery(request)
+          : await readJsonBody(request);
+
+      const result = await service.call(input, actor);
+      const presented = options.present?.(result) ?? { body: result };
+      return json(presented.body ?? { ok: true }, presented.status ?? 200, {
+        headers: presented.headers,
+        cookies: presented.cookies,
+      });
+    } catch (error) {
+      return errorResponse(error, actor);
+    }
+  };
+}

package/dist/template/src/core/i18n/customer.ts

@@ -0,0 +1,187 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Customer locale policy (MASTER.md §4.9, §43 C1.16).
+//
+// A locale is a customer fact, not a property of whichever delivery happens
+// to be rendering it. Portal pages, transactional templates and notification
+// channels all call this file so they cannot quietly disagree about fallback.
+import { eq } from "drizzle-orm";
+import type { Tx } from "@/core/service";
+import { contacts } from "@/core/contacts/schema";
+import { businessProfile } from "@/core/settings/schema";
+import { DEFAULT_LOCALE } from "@/core/i18n";
+
+export interface LocalePolicy {
+  defaultLocale: string;
+  enabledLocales: string[];
+}
+
+export interface ResolvedCustomerLocale extends LocalePolicy {
+  locale: string;
+}
+
+/** Canonical comparison without making callers care about tag casing. */
+function canonical(locale: string): string {
+  try {
+    return Intl.getCanonicalLocales(locale)[0]?.toLowerCase() ?? locale.toLowerCase();
+  } catch {
+    return locale.toLowerCase();
+  }
+}
+
+/**
+ * Resolve an enabled locale, then the configured default, then the platform
+ * default. A regional preference may use the enabled variant of the same
+ * language (fr-CA -> fr) but an unrelated, disabled locale never escapes.
+ */
+export function resolveEnabledLocale(
+  preferred: string | null | undefined,
+  policy: LocalePolicy,
+): string {
+  const enabled = policy.enabledLocales.length > 0
+    ? policy.enabledLocales
+    : [policy.defaultLocale || DEFAULT_LOCALE];
+  const exact = preferred
+    ? enabled.find((locale) => canonical(locale) === canonical(preferred))
+    : undefined;
+  if (exact) return exact;
+
+  if (preferred) {
+    const language = canonical(preferred).split("-")[0];
+    const related = enabled.find(
+      (locale) => canonical(locale).split("-")[0] === language,
+    );
+    if (related) return related;
+  }
+
+  return enabled.find(
+    (locale) => canonical(locale) === canonical(policy.defaultLocale),
+  ) ?? enabled[0] ?? DEFAULT_LOCALE;
+}
+
+/** Read the instance policy inside an existing transaction. */
+export async function customerLocalePolicy(tx: Tx): Promise<LocalePolicy> {
+  const [business] = await tx
+    .select({
+      defaultLocale: businessProfile.defaultLocale,
+      enabledLocales: businessProfile.enabledLocales,
+    })
+    .from(businessProfile)
+    .limit(1);
+  return business ?? {
+    defaultLocale: DEFAULT_LOCALE,
+    enabledLocales: [DEFAULT_LOCALE],
+  };
+}
+
+/** The policy plus one Contact's enabled preference. */
+export async function localeForContact(
+  tx: Tx,
+  contactId: string,
+): Promise<ResolvedCustomerLocale> {
+  const [policy, contact] = await Promise.all([
+    customerLocalePolicy(tx),
+    tx
+      .select({ preferredLocale: contacts.preferredLocale })
+      .from(contacts)
+      .where(eq(contacts.id, contactId))
+      .limit(1)
+      .then((rows) => rows[0]),
+  ]);
+  return {
+    ...policy,
+    locale: resolveEnabledLocale(contact?.preferredLocale, policy),
+  };
+}
+
+/**
+ * Resolve a User through the one Contact identity linked to the customer
+ * account. Staff have no linked customer Contact and therefore use the
+ * business default.
+ */
+export async function localeForUser(
+  tx: Tx,
+  userId: string,
+): Promise<ResolvedCustomerLocale> {
+  const [policy, contact] = await Promise.all([
+    customerLocalePolicy(tx),
+    tx
+      .select({ preferredLocale: contacts.preferredLocale })
+      .from(contacts)
+      .where(eq(contacts.userId, userId))
+      .limit(1)
+      .then((rows) => rows[0]),
+  ]);
+  return {
+    ...policy,
+    locale: resolveEnabledLocale(contact?.preferredLocale, policy),
+  };
+}
+
+export type LocaleRecipient =
+  | { kind: "user"; id: string }
+  | { kind: "contact"; id: string }
+  | { kind: "email"; address: string };
+
+/** Locale snapshot for notification/template fanout. */
+export async function localeForRecipient(
+  tx: Tx,
+  recipient: LocaleRecipient,
+): Promise<ResolvedCustomerLocale> {
+  if (recipient.kind === "contact") return localeForContact(tx, recipient.id);
+  if (recipient.kind === "user") return localeForUser(tx, recipient.id);
+  const policy = await customerLocalePolicy(tx);
+  return { ...policy, locale: resolveEnabledLocale(null, policy) };
+}
+
+const NEVER_PREFIX = /^\/(?:admin|login|setup|preview|api|media)(?:\/|$)/;
+
+/** Default locale is unprefixed; every other enabled customer locale is not. */
+export function localePath(
+  slug: string,
+  locale: string,
+  defaultLocale: string,
+): string {
+  const clean = slug.replace(/^\/+|\/+$/g, "");
+  const path = clean === "" ? "/" : `/${clean}`;
+  return canonical(locale) === canonical(defaultLocale)
+    ? path
+    : `/${locale}${path === "/" ? "" : path}`;
+}
+
+/**
+ * Keep an internal customer link in the selected language. External URLs,
+ * fragments, mail/phone links, assets and owner-only routes are left alone.
+ */
+export function localizeCustomerHref(
+  href: string,
+  locale: string,
+  policy: LocalePolicy,
+): string {
+  if (!href.startsWith("/") || href.startsWith("//")) return href;
+  const match = /^([^?#]*)([?#].*)?$/.exec(href);
+  const path = match?.[1] || "/";
+  const suffix = match?.[2] ?? "";
+  if (NEVER_PREFIX.test(path)) return href;
+
+  const parts = path.split("/");
+  const first = parts[1];
+  const isLocale = first
+    ? policy.enabledLocales.some((candidate) => canonical(candidate) === canonical(first))
+    : false;
+  const bare = isLocale ? `/${parts.slice(2).join("/")}` : path;
+  const clean = bare === "" ? "/" : bare;
+  const localized = localePath(clean, locale, policy.defaultLocale);
+  return `${localized}${suffix}`;
+}
+
+/** A language's own name, suitable for a chooser people can recognize. */
+export function languageName(locale: string): string {
+  try {
+    const display = new Intl.DisplayNames([locale], { type: "language" });
+    const name = display.of(locale);
+    return name ? name.charAt(0).toUpperCase() + name.slice(1) : locale;
+  } catch {
+    return locale;
+  }
+}

package/dist/template/src/core/i18n/index.ts

@@ -0,0 +1,286 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// The string layer (MASTER.md §4.9, §7 step 1): exists before any feature is
+// built. UI strings live in ICU MessageFormat catalogs under /locales —
+// community-translatable JSON; content translations live in the
+// EntityTranslation table (a later step-1 PR). Money helpers enforce the
+// (amount_cents, currency) convention (§2 principle 9): formatting is the
+// only place cents meet decimals.
+import { IntlMessageFormat } from "intl-messageformat";
+import {
+  isLiteralElement,
+  isPluralElement,
+  isSelectElement,
+  isTagElement,
+} from "@formatjs/icu-messageformat-parser";
+import en from "../../../locales/en.json";
+import es from "../../../locales/es.json";
+import fr from "../../../locales/fr.json";
+import ar from "../../../locales/ar.json";
+
+// Statically imported rather than read from disk at runtime: the catalogs must
+// be present in the standalone build output (§14), and a dynamic read would
+// leave them behind. Adding a locale is one import and one entry — and
+// tests/core/i18n-gate.test.ts then requires it to be complete, so a
+// half-finished catalog fails the build rather than falling back to English
+// on the strings nobody got to.
+const catalogs: Record<string, Record<string, string>> = { en, es, fr, ar };
+
+export const DEFAULT_LOCALE = "en";
+/**
+ * A synthesized, deliberately expanded locale for layout and catalog QA.
+ *
+ * It is not in `catalogs`, so it can never appear in the production language
+ * chooser by accident. Tests and local previews may still ask `t()` for it to
+ * expose clipped controls, concatenated copy and strings that bypass catalogs.
+ */
+export const PSEUDO_LOCALE = "en-XA";
+
+export type TextDirection = "ltr" | "rtl";
+
+// Direction belongs to the script, not the language alone: `ar-Latn` is LTR
+// while ordinary Arabic maximizes to Arab and is RTL. `Intl.Locale#maximize`
+// supplies the likely script for tags that omit it.
+const RTL_SCRIPTS = new Set([
+  "Adlm",
+  "Arab",
+  "Aran",
+  "Hebr",
+  "Mand",
+  "Nkoo",
+  "Rohg",
+  "Samr",
+  "Syrc",
+  "Thaa",
+  "Yezi",
+]);
+
+/** The document direction implied by a BCP-47 locale. Invalid tags stay LTR. */
+export function localeDirection(locale: string): TextDirection {
+  try {
+    return RTL_SCRIPTS.has(new Intl.Locale(locale).maximize().script ?? "")
+      ? "rtl"
+      : "ltr";
+  } catch {
+    return "ltr";
+  }
+}
+
+export function availableLocales(): string[] {
+  return Object.keys(catalogs);
+}
+
+const formatterCache = new Map<string, IntlMessageFormat>();
+
+const PSEUDO_GLYPHS: Record<string, string> = {
+  a: "à", b: "ƀ", c: "ç", d: "ð", e: "ë", f: "ƒ", g: "ğ", h: "ħ",
+  i: "ï", j: "ĵ", k: "ķ", l: "ļ", m: "ɱ", n: "ñ", o: "ö", p: "þ",
+  q: "ʠ", r: "ŕ", s: "š", t: "ţ", u: "ü", v: "ṽ", w: "ŵ", x: "ẋ",
+  y: "ÿ", z: "ž",
+  A: "À", B: "Ƀ", C: "Ç", D: "Ð", E: "Ë", F: "Ƒ", G: "Ğ", H: "Ħ",
+  I: "Ï", J: "Ĵ", K: "Ķ", L: "Ļ", M: "Ṁ", N: "Ñ", O: "Ö", P: "Þ",
+  Q: "Ɋ", R: "Ŕ", S: "Š", T: "Ţ", U: "Ü", V: "Ṽ", W: "Ŵ", X: "Ẋ",
+  Y: "Ÿ", Z: "Ž",
+};
+
+type MessageAst = ReturnType<InstanceType<typeof IntlMessageFormat>["getAst"]>;
+
+function pseudoLiteral(value: string): string {
+  const transformed = [...value]
+    .map((character) => PSEUDO_GLYPHS[character] ?? character)
+    .join("");
+  const letters = [...value].filter((character) => /[A-Za-z]/.test(character)).length;
+  return letters > 0
+    ? `${transformed}${"·".repeat(Math.max(1, Math.ceil(letters * 0.3)))}`
+    : transformed;
+}
+
+/** Accent and expand only literal AST nodes, never names or other parameters. */
+function pseudoAst(elements: MessageAst): MessageAst {
+  return elements.map((element) => {
+    if (isLiteralElement(element)) {
+      return { ...element, value: pseudoLiteral(element.value) };
+    }
+    if (isSelectElement(element) || isPluralElement(element)) {
+      return {
+        ...element,
+        options: Object.fromEntries(
+          Object.entries(element.options).map(([key, option]) => [
+            key,
+            { ...option, value: pseudoAst(option.value) },
+          ]),
+        ),
+      };
+    }
+    if (isTagElement(element)) {
+      return { ...element, children: pseudoAst(element.children) };
+    }
+    return element;
+  });
+}
+
+function isPseudoLocale(locale: string): boolean {
+  try {
+    return Intl.getCanonicalLocales(locale)[0] === PSEUDO_LOCALE;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Narrow a BCP-47 tag toward the default: fr-CA → fr → en. Locales in §4.9 are
+ * regional tags, so a Québécois visitor must reach the French catalog before
+ * English is considered at all — a missing region must not undo the language.
+ */
+export function catalogChain(locale: string): string[] {
+  const parts = locale.split("-");
+  const chain = parts.map((_, i) => parts.slice(0, parts.length - i).join("-"));
+  return chain.includes(DEFAULT_LOCALE) ? chain : [...chain, DEFAULT_LOCALE];
+}
+
+/**
+ * Translate a catalog key. Falls back along the language chain, then to the
+ * key itself — loudly in dev, so missing strings surface before the i18n gate
+ * finds them. Formatting always uses the *requested* locale, even when the
+ * string came from a broader catalog, so numbers and dates stay regional.
+ */
+export function t(
+  locale: string,
+  key: string,
+  params?: Record<string, string | number | Date>,
+): string {
+  let message: string | undefined;
+  let from = DEFAULT_LOCALE;
+  for (const candidate of catalogChain(locale)) {
+    const hit = catalogs[candidate]?.[key];
+    if (hit !== undefined) {
+      message = hit;
+      from = candidate;
+      break;
+    }
+  }
+  if (message === undefined) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(`i18n: missing catalog key "${key}" (${locale})`);
+    }
+    return key;
+  }
+  const pseudo = isPseudoLocale(locale);
+  const cacheKey = `${locale}|${from}|${key}`;
+  let formatter = formatterCache.get(cacheKey);
+  if (!formatter) {
+    formatter = pseudo
+      ? new IntlMessageFormat(
+          pseudoAst(new IntlMessageFormat(message, DEFAULT_LOCALE).getAst()),
+          locale,
+        )
+      : new IntlMessageFormat(message, locale);
+    formatterCache.set(cacheKey, formatter);
+  }
+  const formatted = String(formatter.format(params));
+  return pseudo ? `⟦${formatted}⟧` : formatted;
+}
+
+/**
+ * A `t` with the locale already bound.
+ *
+ * Every call site would otherwise repeat the locale it just resolved, and the
+ * one that forgets does not fail — it renders English at a French visitor. So
+ * the locale is decided once, per request, and passed as a function.
+ */
+export type Translate = (
+  key: string,
+  params?: Record<string, string | number | Date>,
+) => string;
+
+export function translator(locale: string): Translate {
+  return (key, params) => t(locale, key, params);
+}
+
+/** Every key in a catalog. Used by the i18n gate to compare catalogs. */
+export function catalogKeys(locale: string): string[] {
+  return Object.keys(catalogs[locale] ?? {});
+}
+
+/**
+ * All money is (amount_minor_units, currency); never floats, never auto-FX.
+ *
+ * "Cents" is a two-decimal assumption, and most of the world isn't. ¥1000 is
+ * 1000 minor units, not 10; 1000 Kuwaiti fils is 1.000 KWD, not 10.000. The
+ * exponent comes from the currency itself, and the decimal string is assembled
+ * by hand and handed to Intl as a string — so no division and no rounding. The
+ * bound is the caller's: a JS number holds exact integers to 2^53 (≈ $90tn in
+ * cents), and this function adds no error of its own (§2 principle 9, §15.4).
+ */
+export function formatMoney(
+  amountMinorUnits: number,
+  currency: string,
+  locale: string = DEFAULT_LOCALE,
+): string {
+  if (!Number.isInteger(amountMinorUnits)) {
+    throw new Error(
+      `formatMoney expects integer minor units, got ${amountMinorUnits} — never do float math on money (MASTER.md §15.4).`,
+    );
+  }
+  const format = new Intl.NumberFormat(locale, { style: "currency", currency });
+  const decimal = moneyDecimal(
+    amountMinorUnits,
+    currency,
+    format.resolvedOptions().maximumFractionDigits ?? 2,
+  );
+  // Intl accepts a decimal string (ES2023), which is what keeps this exact for
+  // amounts past 2^53. TypeScript models that parameter as a template-literal
+  // type no runtime-built string can satisfy, so the assertion narrows a type
+  // rather than claiming anything about the value.
+  return format.format(decimal as Intl.StringNumericLiteral);
+}
+
+/**
+ * The same money as a bare decimal string: 123_456 minor CAD units give
+ * `"1234.56"`, and 1000 Kuwaiti fils give `"1.000"`.
+ *
+ * Split out of `formatMoney` because a machine-read file is not a sentence. A
+ * cell QuickBooks or Xero is going to import has to say `1234.56` rather than
+ * `CA$1,234.56`: the symbol, the grouping separator and the locale's decimal
+ * mark are three separate ways to make an importer read the wrong number, and
+ * a French locale writing `1 234,56` splits the cell in two at the comma.
+ *
+ * It is deliberately the *same* assembly `formatMoney` uses — pad, slice,
+ * insert the point — because the only thing worse than a second money
+ * formatter is a second money formatter that rounds differently. No division
+ * and no floats, here or there (§15.4).
+ */
+export function moneyDecimal(
+  amountMinorUnits: number,
+  currency: string,
+  exponentHint?: number,
+): string {
+  if (!Number.isInteger(amountMinorUnits)) {
+    throw new Error(
+      `money must be integer minor units, got ${amountMinorUnits} — never do float math on money (MASTER.md §15.4).`,
+    );
+  }
+  const exponent =
+    exponentHint ??
+    new Intl.NumberFormat("en", { style: "currency", currency }).resolvedOptions()
+      .maximumFractionDigits ??
+    2;
+  const sign = amountMinorUnits < 0 ? "-" : "";
+  const digits = String(Math.abs(amountMinorUnits)).padStart(exponent + 1, "0");
+  const whole = digits.slice(0, digits.length - exponent);
+  const fraction = digits.slice(digits.length - exponent);
+  return `${sign}${whole}${fraction ? `.${fraction}` : ""}`;
+}
+
+/** Store UTC, display in an explicit timezone (§4.9 timezone discipline). */
+export function formatDateTime(
+  utc: Date,
+  timezone: string,
+  locale: string = DEFAULT_LOCALE,
+): string {
+  return new Intl.DateTimeFormat(locale, {
+    dateStyle: "medium",
+    timeStyle: "short",
+    timeZone: timezone,
+  }).format(utc);
+}

package/dist/template/src/core/i18n/schema.ts

@@ -0,0 +1,59 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Content translations (MASTER.md §4.9).
+//
+// §4.9 draws a line the whole i18n design rests on: **UI strings** live in
+// message catalogs shipped with the platform and translated by the community,
+// while **content** — pages, products, galleries, campaigns — lives here, in
+// the owner's database, because only they can write it.
+//
+// One row per entity per locale, holding the fields that differ. Not a
+// duplicate of the entity: a translated page is the same page with different
+// words, so its slug, its position in the hierarchy and its publication state
+// stay where they are. That is what makes "the French site" the same site
+// rather than a parallel one somebody has to keep in step.
+import {
+  index,
+  jsonb,
+  pgTable,
+  text,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { createdAtColumn, updatedAtColumn } from "@/core/db/columns";
+
+export const entityTranslations = pgTable(
+  "entity_translations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    /** "page", "section", "product" — whatever a module calls its own rows. */
+    entityType: text("entity_type").notNull(),
+    entityId: uuid("entity_id").notNull(),
+    /** BCP-47, and never the default locale: that is the entity itself. */
+    locale: text("locale").notNull(),
+    /** The translated fields. Shape is the entity's business, not core's. */
+    fields: jsonb("fields").notNull().default({}),
+    /**
+     * How much to trust it.
+     *
+     * §4.9 permits machine drafting and forbids publishing it silently, so the
+     * distinction has to survive in the data: `machine` is a draft a human has
+     * not seen, and the renderer treats it as absent on the public surface.
+     */
+    status: text("status", { enum: ["draft", "machine", "reviewed"] })
+      .notNull()
+      .default("draft"),
+    /** "user:<id>", "agent:<key>" — the same actor strings as the audit log. */
+    translatedBy: text("translated_by"),
+    createdAt: createdAtColumn(),
+    updatedAt: updatedAtColumn(),
+  },
+  (t) => [
+    uniqueIndex("entity_translations_key_idx").on(
+      t.entityType,
+      t.entityId,
+      t.locale,
+    ),
+    index("entity_translations_locale_idx").on(t.locale, t.entityType),
+  ],
+);