@k2b/cloud 0.37.0 → 0.39.0

package/src/services/settings/core-settings.ts

@@ -385,15 +385,16 @@ export const CORE_SETTINGS = {
     default: 10000,
     min: 100,
     max: 120000,
-    description: "Maximum time in milliseconds for one Gotenberg render request.",
+    description:
+      "Maximum time in milliseconds for one Gotenberg render request. Gotenberg's own --api-timeout (default 30 s) also caps it.",
   },
   "gotenberg.max_html_bytes": {
     kind: "number",
-    label: "Max HTML Bytes",
+    label: "Max input bytes",
     default: 1048576,
     min: 1024,
     max: 10485760,
-    description: "Maximum HTML input size accepted before sending a render request.",
+    description: "Maximum size of one render request: HTML, header, footer, images and fonts together.",
   },
   "gotenberg.max_pdf_bytes": {
     kind: "number",

package/src/services/settings/index.ts

@@ -3,25 +3,27 @@
  *
  * Resolution order: DB value -> env fallback -> code default.
  *
- * Custom DB values are encrypted at rest using APP_SECRET. All read/write
- * goes through the Redis cache-aside layer in `./store.ts` (5-minute TTL).
+ * Custom DB values are encrypted at rest using APP_SECRET. Value reads use
+ * Redis cache-aside in `./store.ts` (5-minute TTL); stored-state reads use DB.
  * `loadCache()` runs once at boot to normalize legacy rows and bootstrap
- * env-backed entries into Postgres.
+ * env-backed entries into Postgres. Startup never replaces an existing row;
+ * env bootstrap only fills missing keys.
  */
 
 import { redis, sql } from "bun";
 import { decryptValue, encryptValue, getAppSecret } from "./crypto";
 import { resolveSettingPresentation, SETTINGS, SETTINGS_MAP, type SettingDef, validateSettingValue } from "./defaults";
-import { bulkRead, deleteKey, readKey, writeKey } from "./store";
+import { deleteKey, readKey, readKeyState, readStates, type SettingRead, writeKey } from "./store";
 
 type SqlClient = typeof sql;
 
 type StoredRow = { key: string; value: string };
-type PendingRow = { key: string; value: unknown; rewrite: boolean; existed: boolean };
+type PendingRow = { value: unknown; originalCiphertext: string };
 type NormalizationStats = {
   encryptedLoaded: number;
   normalizedUpdated: number;
   envBootstrapped: number;
+  undecryptable: number;
   invalidSkipped: number;
 };
 
@@ -58,23 +60,18 @@ const shouldBootstrapValue = (def: SettingDef, value: unknown): boolean => {
   }
 };
 
-const upsertEncryptedRow = async (key: string, value: unknown): Promise<void> => {
-  const encryptedValue = await encryptValue(value);
-  await sql`
-    INSERT INTO settings.entries (key, value, updated_at)
-    VALUES (${key}, ${encryptedValue}, now())
-    ON CONFLICT (key)
-    DO UPDATE SET value = ${encryptedValue}, updated_at = now()
-  `;
-  await redis.del(REDIS_KEY(key));
-};
-
-const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; value: unknown }>; stats: NormalizationStats }> => {
+const normalizeStoredEntries = async (): Promise<{
+  rows: Array<{ key: string; value: unknown }>;
+  storedKeys: Set<string>;
+  stats: NormalizationStats;
+}> => {
   const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries`;
+  const storedKeys = new Set(rows.map((row) => row.key));
   const stats: NormalizationStats = {
     encryptedLoaded: 0,
     normalizedUpdated: 0,
     envBootstrapped: 0,
+    undecryptable: 0,
     invalidSkipped: 0,
   };
   const pendingRows = new Map<string, PendingRow>();
@@ -82,11 +79,17 @@ const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; va
   for (const row of rows) {
     try {
       const value = await decryptValue(row.value);
-      pendingRows.set(row.key, { key: row.key, value, rewrite: false, existed: true });
+      pendingRows.set(row.key, { value, originalCiphertext: row.value });
       stats.encryptedLoaded += 1;
     } catch {
-      console.warn(`[settings] skipping invalid stored value for "${row.key}"`);
-      stats.invalidSkipped += 1;
+      // An unreadable value is not a missing value (#1295). Usually this
+      // process runs with another APP_SECRET than the writer; applications
+      // with the right key still read this row. Keep its key in `storedKeys`
+      // so env bootstrap never replaces it, and never log the value.
+      console.warn(
+        `[settings] cannot decrypt stored value for "${row.key}" with this APP_SECRET; keeping the row unchanged, reads use the environment fallback or default`,
+      );
+      stats.undecryptable += 1;
     }
   }
 
@@ -109,28 +112,47 @@ const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; va
 
     normalized.push({ key, value: validated.value });
 
-    if (row.rewrite || !row.existed || !isEqual(row.value, validated.value)) {
-      await upsertEncryptedRow(key, validated.value);
-      stats.normalizedUpdated += 1;
+    if (!isEqual(row.value, validated.value)) {
+      const encryptedValue = await encryptValue(validated.value);
+      const updated = await sql<{ key: string }[]>`
+        UPDATE settings.entries SET value = ${encryptedValue}, updated_at = now()
+        WHERE key = ${key} AND value = ${row.originalCiphertext}
+        RETURNING key
+      `;
+      if (updated.length > 0) {
+        await redis.del(REDIS_KEY(key));
+        stats.normalizedUpdated += 1;
+      }
     }
   }
 
-  return { rows: normalized, stats };
+  return { rows: normalized, storedKeys, stats };
 };
 
 const bootstrapEnvBackedEntries = async (config: {
   rows: Array<{ key: string; value: unknown }>;
+  storedKeys: Set<string>;
   stats: NormalizationStats;
 }): Promise<Array<{ key: string; value: unknown }>> => {
   const rowsByKey = new Map(config.rows.map((row) => [row.key, row.value]));
 
   for (const def of SETTINGS) {
-    if (rowsByKey.has(def.key)) continue;
+    // Existing rows block bootstrap even if unreadable, unknown, or invalid.
+    if (config.storedKeys.has(def.key)) continue;
 
     const envValue = resolveEnvValue(def, "bootstrap");
     if (!shouldBootstrapValue(def, envValue)) continue;
 
-    await upsertEncryptedRow(def.key, envValue);
+    const encryptedValue = await encryptValue(envValue);
+    const inserted = await sql<{ key: string }[]>`
+      INSERT INTO settings.entries (key, value, updated_at)
+      VALUES (${def.key}, ${encryptedValue}, now())
+      ON CONFLICT (key) DO NOTHING
+      RETURNING key
+    `;
+    if (inserted.length === 0) continue;
+
+    await redis.del(REDIS_KEY(def.key));
     rowsByKey.set(def.key, envValue);
     config.stats.envBootstrapped += 1;
   }
@@ -140,16 +162,16 @@ const bootstrapEnvBackedEntries = async (config: {
 
 /**
  * Boot-time normalization + env-bootstrap. Runs once at startup. Does NOT
- * populate any in-process cache — every read goes through Redis cache-aside
- * (`store.ts`) at request time.
+ * populate any in-process cache — value reads use Redis cache-aside
+ * (`store.ts`), and stored-state reads go directly to Postgres.
  */
 export async function loadCache(): Promise<void> {
   getAppSecret();
-  const { rows, stats } = await normalizeStoredEntries();
-  const bootstrappedRows = await bootstrapEnvBackedEntries({ rows, stats });
+  const { rows, storedKeys, stats } = await normalizeStoredEntries();
+  const bootstrappedRows = await bootstrapEnvBackedEntries({ rows, storedKeys, stats });
 
   console.log(
-    `[settings] loaded ${bootstrappedRows.length} custom setting(s) (${stats.encryptedLoaded} encrypted, ${stats.normalizedUpdated} normalized, ${stats.envBootstrapped} env-bootstrapped, ${stats.invalidSkipped} skipped)`,
+    `[settings] loaded ${bootstrappedRows.length} custom setting(s) (${stats.encryptedLoaded} encrypted, ${stats.normalizedUpdated} normalized, ${stats.envBootstrapped} env-bootstrapped, ${stats.undecryptable} undecryptable, ${stats.invalidSkipped} skipped)`,
   );
 }
 
@@ -165,8 +187,12 @@ export async function get<T = unknown>(key: string): Promise<T> {
  * Write a setting. Pass `db` to run inside a caller's transaction — then the
  * caller must also call `invalidateSettingsCache` once it commits.
  */
-export async function set(key: string, value: unknown, db?: SqlClient): Promise<void> {
-  await writeKey(key, value, db);
+export async function set(key: string, value: unknown, db?: SqlClient, options?: { replaceUnreadable?: boolean }): Promise<void> {
+  await writeKey(key, value, db, options);
+}
+
+export async function read(key: string): Promise<SettingRead> {
+  return readKeyState(key);
 }
 
 export async function remove(key: string, db?: SqlClient): Promise<void> {
@@ -176,20 +202,17 @@ export async function remove(key: string, db?: SqlClient): Promise<void> {
 import type { SettingEntry } from "../../contracts/shared";
 
 export type { SettingEntry } from "../../contracts/shared";
-export { invalidateSettingsCache } from "./store";
+export type { SettingRead, StoredSettingState } from "./store";
+export { invalidateSettingsCache, readStates, SettingUnreadableError } from "./store";
 
 export async function getAll(locale?: string): Promise<SettingEntry[]> {
-  // Determine which keys have a custom row in Postgres (vs. falling back to
-  // env / code default). One indexed scan, then bulk-read all values.
-  const customRows = await sql<{ key: string }[]>`SELECT key FROM settings.entries`;
-  const customKeys = new Set(customRows.map((row) => row.key));
-
   const allKeys = SETTINGS.map((def) => def.key);
-  const values = await bulkRead(allKeys);
+  const values = await readStates(allKeys);
 
   return SETTINGS.map((def) => {
     const presentation = resolveSettingPresentation(def, locale);
-    const isCustom = customKeys.has(def.key);
+    const { value, stored } = values.get(def.key)!;
+    const isCustom = stored !== "none";
     const envFallback = resolveEnvValue(def, "fallback");
     const resetValue = envFallback ?? def.default;
 
@@ -200,12 +223,13 @@ export async function getAll(locale?: string): Promise<SettingEntry[]> {
       description: presentation.description ?? "",
       placeholder: presentation.placeholder,
       group: def.group,
-      value: values.get(def.key),
+      value,
       default: def.default,
       resetValue: def.kind === "secret" ? "" : resetValue,
-      valueSource: isCustom ? "custom" : envFallback === undefined ? "default" : "env",
+      valueSource: stored === "readable" ? "custom" : envFallback === undefined ? "default" : "env",
       resetValueSource: envFallback === undefined ? "default" : "env",
       isCustom,
+      unreadable: stored === "unreadable",
       templateVars: "templateVars" in def ? def.templateVars : undefined,
       options: presentation.options,
       min: "min" in def ? def.min : undefined,

package/src/services/settings/namespace.ts

@@ -1,8 +1,9 @@
-import { get, getAll, loadCache, remove, set } from "./index";
+import { get, getAll, loadCache, read, remove, set } from "./index";
 
 export const settings = {
   loadCache,
   get,
+  read,
   set,
   remove,
   getAll,

package/src/services/settings/store.ts

@@ -1,7 +1,7 @@
 /**
  * Settings store — Redis cache-aside read/write primitives.
  *
- * Pattern: each key is cached in Redis with a 5-minute TTL. Reads try Redis
+ * Pattern: each key is cached in Redis with a 5-minute TTL. Value reads try Redis
  * first, fall back to DB on miss, and populate Redis. Writes update DB and
  * delete the Redis key (next reader repopulates with fresh DB state).
  *
@@ -27,6 +27,19 @@ const REDIS_KEY = (k: string) => `settings:${k}`;
 
 type SqlClient = typeof sql;
 
+export type StoredSettingState = "none" | "readable" | "unreadable";
+export type SettingRead = { value: unknown; stored: StoredSettingState };
+
+export class SettingUnreadableError extends HTTPException {
+  readonly code = "setting_unreadable" as const;
+
+  constructor(readonly key: string) {
+    const message = `The stored value of setting "${key}" cannot be read by this application. Replace it with a new value or reset it to the default.`;
+    super(409, { message, res: Response.json({ code: "setting_unreadable", message }, { status: 409 }) });
+    this.name = "SettingUnreadableError";
+  }
+}
+
 /**
  * Forget cached values so every container re-reads on next access.
  *
@@ -70,6 +83,12 @@ const resolveFallback = (def: SettingDef | undefined): unknown => {
  */
 export const readKey = async (key: string): Promise<unknown> => (await bulkRead([key])).get(key);
 
+export const readKeyState = async (key: string): Promise<SettingRead> => {
+  const state = (await readStates([key])).get(key);
+  if (!state) throw new Error(`Missing read state for setting "${key}"`);
+  return state;
+};
+
 /** One warm MGET; missing rows are cached independently of local env/defaults. */
 export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unknown>> => {
   const result = new Map<string, unknown>();
@@ -131,6 +150,32 @@ export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unk
   return result;
 };
 
+/**
+ * Stored state is per process (APP_SECRET), but the plaintext cache is shared.
+ * State reads go directly to Postgres without reading or filling the cache;
+ * value reads (`get`, snapshot) keep using the cache.
+ */
+export const readStates = async (keys: readonly string[]): Promise<Map<string, SettingRead>> => {
+  const result = new Map<string, SettingRead>();
+  if (keys.length === 0) return result;
+  const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray([...keys])}::text[])`;
+  const byKey = new Map(rows.map((row) => [row.key, row]));
+  for (const key of keys) {
+    const row = byKey.get(key);
+    const def = SETTINGS_MAP.get(key);
+    result.set(key, { stored: row ? "unreadable" : "none", value: resolveFallback(def) });
+    if (!row) continue;
+    try {
+      const value = await decryptValue(row.value);
+      const validated = def ? validateSettingValue(def, value) : { ok: true as const, value };
+      if (validated.ok) result.set(key, { stored: "readable", value: validated.value });
+    } catch {
+      // Keep this process's fallback without changing the stored row or cache.
+    }
+  }
+  return result;
+};
+
 /**
  * Get every known setting key (across all registered defs).
  * Used by snapshot loader to determine what to bulk-read.
@@ -184,11 +229,12 @@ export const deleteLegacyKeys = async (extraKnownKeys: readonly string[] = []):
 /**
  * Encrypt the value, upsert the DB row, invalidate the Redis key.
  *
- * Validation is the caller's responsibility — the typed wrapper API
- * (createSettingsAPI) validates against the declared SettingDef before reaching
- * here. Direct callers must ensure the value matches the setting's kind.
+ * Validate new values and refuse to overwrite unreadable stored rows unless
+ * the caller explicitly replaces them. The row check and write share a transaction.
+ * Lock with a no-op UPDATE so ROW EXCLUSIVE is acquired before the row lock,
+ * preserving lock order with table-level SHARE locks (#1303 review).
  */
-export const writeKey = async (key: string, value: unknown, db?: SqlClient): Promise<void> => {
+export const writeKey = async (key: string, value: unknown, db?: SqlClient, options?: { replaceUnreadable?: boolean }): Promise<void> => {
   const def = SETTINGS_MAP.get(key);
   if (!def) throw new Error(`Unknown setting: ${key}`);
   const validated = validateSettingValue(def, value);
@@ -197,12 +243,38 @@ export const writeKey = async (key: string, value: unknown, db?: SqlClient): Pro
   const storedValue =
     def.kind === "image" && typeof validated.value === "string" ? stripImageDataUrlMetadata(validated.value) : validated.value;
   const encrypted = await encryptValue(storedValue);
-  await (db ?? sql)`
-    INSERT INTO settings.entries (key, value, updated_at)
-    VALUES (${key}, ${encrypted}, now())
-    ON CONFLICT (key)
-    DO UPDATE SET value = ${encrypted}, updated_at = now()
-  `;
+  const write = async (tx: SqlClient) => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      let [row] = await tx<{ value: string }[]>`UPDATE settings.entries SET value = value WHERE key = ${key} RETURNING value`;
+      if (!row) {
+        const inserted = await tx<{ key: string }[]>`
+          INSERT INTO settings.entries (key, value, updated_at)
+          VALUES (${key}, ${encrypted}, now())
+          ON CONFLICT (key) DO NOTHING RETURNING key
+        `;
+        if (inserted.length > 0) return;
+        // A concurrent insert can win after the missing-row read; lock and check its value before updating.
+        [row] = await tx<{ value: string }[]>`UPDATE settings.entries SET value = value WHERE key = ${key} RETURNING value`;
+        if (!row) continue;
+      }
+      if (options?.replaceUnreadable !== true) {
+        let readable = false;
+        try {
+          readable = validateSettingValue(def, await decryptValue(row.value)).ok;
+        } catch {
+          // Only the key is exposed by the recovery error.
+        }
+        if (!readable) throw new SettingUnreadableError(key);
+      }
+      await tx`
+        UPDATE settings.entries SET value = ${encrypted}, updated_at = now() WHERE key = ${key}
+      `;
+      return;
+    }
+    throw new Error(`Could not write setting "${key}" after 3 attempts`);
+  };
+  if (db) await write(db);
+  else await sql.begin(write);
 
   // Passing a transaction means the caller owns invalidation, because the row
   // is not visible to anyone else until they commit.

package/src/shared/ai-platform-prompt.ts

@@ -59,7 +59,7 @@ Most replies need no offer. Make at most one offer, in the last sentence of the
 {%- if memoryToolEnabled %}
 - The user corrected the tone of a result, such as a mail that is too formal, without stating a lasting rule: offer to remember it as their preference. Memory keeps only the user's own words, so a plain yes cannot be saved: suggest a one-line rule they can send back, such as "Always write mails casually and briefly".
 {%- endif %}
-- The user says the request recurs (again, every week, like last time, always), pastes a long reusable instruction, or a workflow default covers it: offer to save it as a {% if skillOffers %}Skill or {% endif %}scheduled task.
+- The user says the request recurs (again, every week, like last time, always), pastes a long reusable instruction, or a workflow default covers it: offer to save it as a {% if skillOffers %}Skill or {% endif %}routine.
 - A concrete next step clearly saves the user real work they may not know you can do: offer it, such as a manual follow-up the user mentioned, drafting the reply, or turning findings into Space tasks.
 Offer only what the Skills, tool hints, and apps in this prompt support. Do not search mail, chats, or other data only to justify an offer, and do not claim how often something happened unless the user said it or this chat shows it. Do not start the offered work until the user agrees.
 {%- if skillOffers %}

package/src/shared/app-presentation.ts

@@ -65,6 +65,7 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
   return {
     ...app,
     ...resolveAppIdentityPresentation(app, requestedLocale),
+    ...(app.panel ? { panel: { ...app.panel, label: translation.panelLabel ?? app.panel.label } } : {}),
     adminNav: app.adminNav?.map((group) => ({
       ...group,
       label: (group.id && translation.adminGroups?.[group.id]) || group.label,

package/src/shared/help.ts

@@ -1,5 +1,39 @@
 import { localeFallbackChain } from "./locale";
 
+export const HELP_KINDS = ["start", "task", "reference", "troubleshoot"] as const;
+export type HelpKind = (typeof HELP_KINDS)[number];
+/** The glossary's access levels; Help names only these, never app-specific permissions. */
+export const HELP_ACCESS_LEVELS = ["view", "edit", "manage"] as const;
+export type HelpAccessLevel = (typeof HELP_ACCESS_LEVELS)[number];
+/** An article another article points to, resolved for the current reader. */
+export type HelpArticleLink = {
+  appId: string;
+  appName: string;
+  /** The target app's accent colour (registry appearance), when it declares one. */
+  accent?: string;
+  documentId: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  /** Canonical page path: `/help/apps/<appId>/<documentId>`. */
+  url: string;
+};
+
+export type HelpLinkResolver = (ref: { appId?: string; documentId: string }) => HelpArticleLink | undefined;
+
+/** References have the same app-id grammar as capability declarations. */
+export const HELP_REFERENCE_PATTERN = /^(?:[a-z][a-z0-9-]*\/)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const parseHelpReference = (value: string): { appId?: string; documentId: string; fragment: string } | undefined => {
+  const [reference = "", ...fragments] = value.split("#");
+  if (!HELP_REFERENCE_PATTERN.test(reference)) return undefined;
+  const parts = reference.split("/");
+  return {
+    appId: parts.length === 2 ? parts[0] : undefined,
+    documentId: parts.at(-1)!,
+    fragment: fragments.length ? `#${fragments.join("#")}` : "",
+  };
+};
+
 export type HelpDocumentManifest = {
   /** Resolved content locale on central Help manifests. */
   locale?: string;
@@ -8,6 +42,8 @@ export type HelpDocumentManifest = {
   icon?: string;
   description?: string;
   order: number;
+  /** Where the Help start lists the article; missing means `task`. */
+  kind?: HelpKind;
   /** Core-owned endpoint used for debounced full-text search. */
   searchUrl: string;
   url: string;
@@ -24,8 +60,13 @@ export type HelpDocumentPayload = {
   locale: string;
   id: string;
   title: string;
+  /** Agent text with Help-only presentation converted to portable Markdown. */
   markdown: string;
   html: string;
+  kind: HelpKind;
+  needs?: HelpAccessLevel;
+  next?: HelpArticleLink;
+  related: HelpArticleLink[];
 };
 
 /** Exact locale, then BCP 47 ancestors, then the corpus base locale. */

package/src/shared/index.ts

@@ -46,7 +46,15 @@ export * from "./login-method";
 export { markdown } from "./markdown";
 export { markdownCalloutSanitizeOptions } from "./markdown/callout-sanitizer";
 export type { ErrorCode, EvalContext, EvalError, EvalResult, EvalValue, ProgressValue } from "./markdown/formula";
-export { createProgressValue, evaluateFormula, formatValue, isFormula, isTotalRow, parseProgressValue } from "./markdown/formula";
+export {
+  createProgressValue,
+  evaluateFormula,
+  evaluateTableCell,
+  formatValue,
+  isFormula,
+  isTotalRow,
+  parseProgressValue,
+} from "./markdown/formula";
 export type { MockCover, MockCoverIcon, MockCoverOptions, MockCoverTheme } from "./mock-cover";
 export { createMockCover, createMockCoverSvg, parseDataUrl } from "./mock-cover";
 export * from "./network-address";