cartethyia 2.7.3 → 2.7.5

package/src/console/share/share-stats.ts

@@ -17,6 +17,10 @@ import { type TelemetryEventRecord } from "../../observability/event-log";
 import {
   queryTelemetryEvents as querySqlEvents,
   sumTelemetryTokens,
+  familyKpiTotals,
+  familyWindowRequests,
+  familyHourlyTelemetry,
+  familyIpBreakdown,
 } from "../../observability/event-query";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { apiKeys } from "../../persistence/schema";
@@ -26,7 +30,7 @@ import { cachedRead } from "../shared/read-through-cache";
 import { utcDayStart, utcMonthStart } from "../shared/day";
 
 /** Totals for the whole share family, all-time plus the windows the UI draws. */
-export interface ShareFamilyTotals {
+interface ShareFamilyTotals {
   readonly requests: number;
   readonly errors: number;
   readonly inputTokens: number;
@@ -41,7 +45,7 @@ export interface ShareFamilyTotals {
 }
 
 /** One hour bucket of the last 24 hours, oldest first. */
-export interface ShareHourlyBucket {
+interface ShareHourlyBucket {
   /** ISO instant at the top of the hour. */
   readonly hour: string;
   readonly requests: number;
@@ -49,7 +53,7 @@ export interface ShareHourlyBucket {
   readonly tokens: number;
 }
 
-export interface ShareTopModel {
+interface ShareTopModel {
   readonly modelId: string;
   readonly requests: number;
   readonly tokens: number;
@@ -59,7 +63,7 @@ export interface ShareTopModel {
   readonly avgTtfbMs: number | null;
 }
 
-export interface ShareTopClientIp {
+interface ShareTopClientIp {
   /** Always masked: this payload is served to the recipient, not the tenant. */
   readonly ip: string;
   readonly requests: number;
@@ -72,6 +76,12 @@ export interface ShareTopClientIp {
    * the tool rather than the machine.
    */
   readonly clientType: string | null;
+  /**
+   * True when this address made a request within {@link ACTIVE_IP_WINDOW_MS}.
+   * A recipient watching the link can tell which addresses are still using it
+   * versus ones that stopped days ago.
+   */
+  readonly active: boolean;
 }
 
 export interface ShareFamilyStats {
@@ -111,6 +121,24 @@ export interface ShareStatsPort {
 
 const HOUR_MS = 3_600_000;
 
+/**
+ * How old an address's last request may be and still count as active on the
+ * share page. 24 hours matches the page's own "last 24 hours" framing: an IP
+ * that made a request since yesterday is "active", one that stopped before
+ * that window is "inactive".
+ */
+const ACTIVE_IP_WINDOW_MS = 24 * HOUR_MS;
+
+/**
+ * Recency window for the client-IP ranking's *work set*: the GROUP BY only
+ * scans this slice of telemetry instead of the whole retained window every
+ * tick. Within the window, addresses are ranked by request volume (highest
+ * first), and older addresses fall out of the ranking entirely. 7 days keeps
+ * the ranking useful while staying orders of magnitude smaller than the
+ * retained window.
+ */
+const IP_WINDOW_MS = 7 * 24 * HOUR_MS;
+
 /**
  * Names the client behind a request from its User-Agent.
  *
@@ -154,7 +182,7 @@ interface FamilyRollup {
   totals: ShareFamilyTotals;
   byHour: Map<string, { requests: number; tokens: number }>;
   models: Map<string, { modelId: string; requests: number; tokens: number; rateSum: number; rateCount: number; ttfbSum: number; ttfbCount: number }>;
-  ips: Map<string, { ip: string; requests: number; tokens: number; lastSeenAt: string | null; userAgent: string | null }>;
+  ips: Map<string, { ip: string; requests: number; tokens: number; lastSeenAt: string | null; userAgent: string | null; active: boolean }>;
 }
 
 /**
@@ -163,7 +191,7 @@ interface FamilyRollup {
  */
 function rollupFamily(
   events: readonly TelemetryEventRecord[],
-  bounds: { dayStart: number; monthStart: number; lastHourStart: number; windowStart: number; allowed: ReadonlySet<string> | null },
+  bounds: { dayStart: number; monthStart: number; lastHourStart: number; windowStart: number; activeIpCutoff: number; allowed: ReadonlySet<string> | null },
 ): FamilyRollup {
   const totals = { requests: 0, errors: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0, lastHourRequests: 0, todayTokens: 0, monthTokens: 0 };
   const byHour = new Map<string, { requests: number; tokens: number }>();
@@ -196,13 +224,14 @@ function rollupFamily(
       models.set(event.requestedModel, model);
     }
     if (event.clientIp !== null) {
-      const ip = ips.get(event.clientIp) ?? { ip: event.clientIp, requests: 0, tokens: 0, lastSeenAt: null, userAgent: null };
+      const ip = ips.get(event.clientIp) ?? { ip: event.clientIp, requests: 0, tokens: 0, lastSeenAt: null, userAgent: null, active: false };
       ip.requests += 1;
       ip.tokens += tokens;
       // Events arrive newest first, so the first one seen is the most recent.
       if (ip.lastSeenAt === null) {
         ip.lastSeenAt = event.createdAt;
         ip.userAgent = event.userAgent;
+        ip.active = at >= bounds.activeIpCutoff;
       }
       ips.set(event.clientIp, ip);
     }
@@ -244,17 +273,18 @@ const HOURS_WINDOW = 24;
 /**
  * Cache lifetime for one family's rollup.
  *
- * Matched to the share page's SSE tick, which was the point of the old 2 s
- * value — but at 2 s the cache expired on every tick, so every single push was
- * a full parse of the retained telemetry window. A share page's numbers move
- * when a request does, not every 2 s; 10 s still reads as live, and cuts the
- * parse rate by five.
+ * Longer than the SSE tick (30s) so most ticks are served from cache. The
+ * cold-compute path reads the family's telemetry windows (24h chart, 7d IP
+ * ranking), which on a busy family is the single most expensive thing the
+ * share page does; a 5-minute TTL caps that to once per family per 5
+ * minutes while the page still reads as live — KPI numbers move with
+ * traffic, not on a per-minute cadence.
  *
  * Declared here rather than imported from the router so this port does not
- * depend on it. `SHARE_STATS_STREAM_INTERVAL_MS` must be raised with it, or
- * the two drift apart and the cache expires between ticks for no reason.
+ * depend on it. `SHARE_STATS_STREAM_INTERVAL_MS` must stay below it, or the
+ * tick and cache drift apart and every tick bypasses the cache.
  */
-export const SHARE_STATS_CACHE_TTL_SECONDS = 10;
+export const SHARE_STATS_CACHE_TTL_SECONDS = 300;
 
 /**
  * Cache key for one family's rollup. The family is named by its template key
@@ -318,17 +348,23 @@ async function computeFamilyStatsBody(
   const hourStart = utcHourStart(now);
   const lastHourStart = new Date(now.getTime() - HOUR_MS);
   const windowStart = new Date(hourStart.getTime() - (HOURS_WINDOW - 1) * HOUR_MS);
+  // The IP breakdown is bounded to this recency window: a family's "who is
+  // using the link" answer only needs addresses that were active recently,
+  // and an unbounded GROUP BY over every retained event is the one remaining
+  // full-window scan on the share page.
+  const ipWindowStart = new Date(now.getTime() - IP_WINDOW_MS);
 
-  // All-time and today's/month's spend come from SQL aggregates, not from the
-  // bounded page below. The page is capped so a very large family cannot pull
-  // the whole table, which means it cannot carry the all-time total. Lifetime,
-  // daily, and monthly are therefore separate bounded sums over the retained
-  // SQL window (each is a single `SUM` aggregate, not a row materialization).
-  // The page's events feed only the hourly chart and the two ranked tables.
-  const [totalTokens, todayTokens, monthTokens, template] = await Promise.all([
-    sumTelemetryTokens(db, tenantId, { familyKeyId: templateKeyId, since: new Date(0) }),
+  // All-time family KPI comes from the durable rollup
+  // (`telemetry_usage_totals`, charged at write time), not from re-aggregating
+  // the entire retained telemetry window on every tick: the share page's tick
+  // would otherwise read every event a busy family ever produced just to draw
+  // four numbers. Today's/month's spend and the last-hour count are bounded
+  // window reads over the time index, which stay small.
+  const [kpi, todayTokens, monthTokens, lastHourRequests, template] = await Promise.all([
+    familyKpiTotals(db, tenantId, templateKeyId),
     sumTelemetryTokens(db, tenantId, { familyKeyId: templateKeyId, since: dayStart }),
     sumTelemetryTokens(db, tenantId, { familyKeyId: templateKeyId, since: monthStart }),
+    familyWindowRequests(db, tenantId, templateKeyId, lastHourStart),
     db
       .select({ lifetime: apiKeys.lifetimeTokensConsumed })
       .from(apiKeys)
@@ -342,8 +378,9 @@ async function computeFamilyStatsBody(
   // across the overview, the share dialog, and this page.
   const templateLifetime = Number(template[0]?.lifetime ?? 0);
 
-  // The hourly chart covers the last 24 hours, so the page only needs events
-  // in that window — not the whole retained history. Bounded and small.
+  // The ranked tables need real events, bounded to the 24-hour window. The
+  // totals and hourly chart are computed in SQL, so the page cap here only
+  // shapes the model/IP rankings — never the KPI numbers.
   const page = await querySqlEvents(db, {
     tenantId,
     familyApiKeyId: templateKeyId,
@@ -356,6 +393,7 @@ async function computeFamilyStatsBody(
     monthStart: monthStart.getTime(),
     lastHourStart: lastHourStart.getTime(),
     windowStart: windowStart.getTime(),
+    activeIpCutoff: now.getTime() - ACTIVE_IP_WINDOW_MS,
     allowed: allowedSet,
   });
   rollup.totals = {
@@ -363,14 +401,28 @@ async function computeFamilyStatsBody(
     // The template counter is the seed on the running total, not a distinct
     // bucket: daily/monthly windows are telemetry-only (the counter has no
     // time axis), so those keep their own sums.
-    totalTokens: templateLifetime + totalTokens,
+    totalTokens: templateLifetime + kpi.tokens,
     todayTokens,
     monthTokens,
+    // Lifetime counts come from the durable rollup, not the page: a family
+    // busier than the page cap must not freeze at 500 requests/errors.
+    requests: kpi.requests,
+    errors: kpi.errors,
+    lastHourRequests,
   };
 
-  // Fill the 24 buckets in JS: only hours that saw traffic are present, and
-  // a chart drawn from sparse rows would silently compress the axis.
-  const byHour = rollup.byHour;
+  // The hourly chart is a SQL aggregate over the whole family window, so a
+  // busy family's bars stay true. Buckets are filled in JS because only hours
+  // that saw traffic are present; a chart drawn from sparse rows would
+  // silently compress the axis.
+  const bucketSeconds = HOUR_MS / 1000;
+  const sqlHourly = await familyHourlyTelemetry(db, tenantId, templateKeyId, windowStart, bucketSeconds);
+  const byHour = new Map(
+    sqlHourly.map((bucket) => [
+      new Date(bucket.at).toISOString(),
+      { requests: bucket.requests, tokens: bucket.inputTokens + bucket.outputTokens },
+    ]),
+  );
   const hourly: ShareHourlyBucket[] = [];
   for (let index = 0; index < HOURS_WINDOW; index += 1) {
     const hour = new Date(windowStart.getTime() + index * HOUR_MS).toISOString();
@@ -378,6 +430,33 @@ async function computeFamilyStatsBody(
     hourly.push({ hour, requests: bucket?.requests ?? 0, tokens: bucket?.tokens ?? 0 });
   }
 
+  // Client IPs come from a SQL aggregate over a bounded recent window, ranked
+  // by request volume — so a family's "who is using the link most" answer
+  // stays cheap instead of scanning the whole retained telemetry on every
+  // tick. `clientType` is best-effort from the page's events (the most recent
+  // 24 hours), which carry the User-Agent.
+  const ipRows = await familyIpBreakdown(db, tenantId, templateKeyId, TOP_IPS_LIMIT, ipWindowStart);
+  const clientTypeByIp = new Map<string, string | null>();
+  for (const event of events) {
+    if (event.clientIp !== null && !clientTypeByIp.has(event.clientIp)) {
+      clientTypeByIp.set(event.clientIp, clientTypeFromUserAgent(event.userAgent));
+    }
+  }
+  const activeIpCutoff = now.getTime() - ACTIVE_IP_WINDOW_MS;
+  const clientIps = ipRows.map((row) => {
+    const lastSeenAt =
+      row.lastSeenAt instanceof Date ? row.lastSeenAt : new Date(String(row.lastSeenAt ?? ""));
+    const lastSeenMs = Number.isFinite(lastSeenAt.getTime()) ? lastSeenAt.getTime() : 0;
+    return {
+      ip: maskClientIp(row.ip),
+      requests: row.requests,
+      tokens: row.tokens,
+      lastSeenAt: lastSeenMs > 0 ? lastSeenAt.toISOString() : null,
+      clientType: clientTypeByIp.get(row.ip) ?? null,
+      active: lastSeenMs >= activeIpCutoff,
+    };
+  });
+
   return {
     totals: rollup.totals,
     hourly,
@@ -391,15 +470,6 @@ async function computeFamilyStatsBody(
         avgTokensPerSec: row.rateCount > 0 ? row.rateSum / row.rateCount : null,
         avgTtfbMs: row.ttfbCount > 0 ? Math.round(row.ttfbSum / row.ttfbCount) : null,
       })),
-    clientIps: [...rollup.ips.values()]
-      .sort((a, b) => b.requests - a.requests)
-      .slice(0, TOP_IPS_LIMIT)
-      .map((row) => ({
-        ip: maskClientIp(row.ip),
-        requests: row.requests,
-        tokens: row.tokens,
-        lastSeenAt: row.lastSeenAt,
-        clientType: clientTypeFromUserAgent(row.userAgent),
-      })),
+    clientIps,
   };
 }

package/src/console/share/share-usage.ts

@@ -13,7 +13,7 @@ import { apiKeys, telemetryUsageTotals } from "../../persistence/schema";
 import { shouldMaskClientIp } from "../shared/ip-privacy";
 import { utcDayStart } from "../shared/day";
 
-export interface SharedKeyTokenUsage {
+interface SharedKeyTokenUsage {
   readonly requests: number;
   readonly errors: number;
   readonly inputTokens: number;

package/src/console/shared/errors.ts

@@ -7,7 +7,7 @@ import { formatPublicErrorMessage } from "../../protocol/gateway-error";
 // (or the storage-layer BackupError, same code/status/message shape) and
 // shapes it through errorResponse; guards narrow to TenantAccessDecision.
 
-export interface ErrorResponseOptions {
+interface ErrorResponseOptions {
   readonly detailsPolicy?: "omit" | "include-if-present" | "always-include";
 }
 
@@ -105,7 +105,7 @@ export function requireAnyScope(
   return access;
 }
 
-export type TenantAccessDecision = AccessDecision & { readonly tenantId: string };
+type TenantAccessDecision = AccessDecision & { readonly tenantId: string };
 
 export function requireTenantScope(
   access: AccessDecision | undefined,

package/src/console/shared/object.ts

@@ -0,0 +1,18 @@
+/**
+ * Builds an object from `source`, omitting absent values.
+ *
+ * The console domains hand-roll the same `...(x === undefined ? {} : { x })`
+ * field-omission spread many times (key create/update patches, response
+ * sanitizers). This is the single helper for that pattern; `omitNull` extends
+ * it to also drop `null` values (the `== null` variant), matching call sites
+ * that treat null as "clear this field" rather than "set it to null".
+ */
+export function pickDefined<T extends object>(source: T, omitNull = false): { [K in keyof T]?: Exclude<T[K], undefined> } {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    if (omitNull && value === null) continue;
+    out[key] = value;
+  }
+  return out as { [K in keyof T]?: Exclude<T[K], undefined> };
+}

package/src/console/shared/read-through-cache.ts

@@ -31,7 +31,7 @@
 import { createHash } from "node:crypto";
 
 /** The slice of Redis this cache needs, so it can be tested without a server. */
-export interface ReadThroughCacheClient {
+interface ReadThroughCacheClient {
   get(key: string): Promise<string | null>;
   set(key: string, value: string, mode: "EX", ttlSeconds: number): Promise<unknown>;
 }
@@ -41,7 +41,7 @@ export interface ReadThroughCacheClient {
  * more often pass a shorter TTL; this value suits the dashboard's polling
  * cadence and the append-only telemetry log.
  */
-export const READ_THROUGH_DEFAULT_TTL_SECONDS = 10;
+const READ_THROUGH_DEFAULT_TTL_SECONDS = 10;
 
 /** The cached value plus the strong validator for the bytes it serializes to. */
 export interface CachedResult<T> {
@@ -59,10 +59,38 @@ function etagFor(bytes: string): string {
 }
 
 /** The sibling key holding the validator, so a cached body is never re-hashed. */
-export function etagKey(key: string): string {
+function etagKey(key: string): string {
   return `${key}:etag`;
 }
 
+/**
+ * In-memory fallback store used when no Redis client is configured (the
+ * embedded lite backend). Keyed by the same cache key, storing the value and
+ * its validator with a TTL. Bounded so a busy gateway cannot grow it without
+ * limit.
+ */
+const LOCAL_CACHE_MAX_ENTRIES = 2000;
+const localCache = new Map<string, { at: number; value: string; etag: string }>();
+
+function localGet(key: string): { value: string; etag: string } | undefined {
+  const entry = localCache.get(key);
+  if (entry === undefined) return undefined;
+  if (Date.now() - entry.at >= READ_THROUGH_DEFAULT_TTL_SECONDS * 1000) {
+    localCache.delete(key);
+    return undefined;
+  }
+  return { value: entry.value, etag: entry.etag };
+}
+
+function localSet(key: string, value: string, etag: string): void {
+  if (localCache.size >= LOCAL_CACHE_MAX_ENTRIES) {
+    // Evict the oldest entry (Map iterates in insertion order).
+    const oldest = localCache.keys().next();
+    if (!oldest.done) localCache.delete(oldest.value);
+  }
+  localCache.set(key, { at: Date.now(), value, etag });
+}
+
 /**
  * Reads through the cache and returns a strong validator alongside the value.
  *
@@ -74,7 +102,8 @@ export function etagKey(key: string): string {
  * With no cache configured (`client === undefined`) the value is computed and
  * the validator is still returned, so conditional requests keep working for
  * the length of the client's own polling loop; only the cross-instance sharing
- * is lost.
+ * is lost. A process-local Map serves the same TTL when Redis is absent, so a
+ * poller still gets cache hits.
  */
 export async function cachedReadWithEtag<T>(
   client: ReadThroughCacheClient | undefined,
@@ -83,8 +112,15 @@ export async function cachedReadWithEtag<T>(
   ttlSeconds: number = READ_THROUGH_DEFAULT_TTL_SECONDS,
 ): Promise<CachedResult<T>> {
   if (client === undefined) {
+    const entry = localGet(key);
+    if (entry !== undefined) {
+      return { value: JSON.parse(entry.value) as T, etag: entry.etag };
+    }
     const fresh = await compute();
-    return { value: fresh, etag: etagFor(JSON.stringify(fresh) ?? "null") };
+    const bytes = JSON.stringify(fresh) ?? "null";
+    const etag = etagFor(bytes);
+    localSet(key, bytes, etag);
+    return { value: fresh, etag };
   }
   try {
     const hit = await client.get(key);
@@ -160,7 +196,7 @@ export function conditionalResponse<T>(
 }
 
 /** True when an `If-None-Match` header names this validator. */
-export function matchesEtag(header: string | null, etag: string): boolean {
+function matchesEtag(header: string | null, etag: string): boolean {
   if (header === null) return false;
   const trimmed = header.trim();
   if (trimmed === "*") return true;

package/src/console/shared/transaction.ts

@@ -0,0 +1,14 @@
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
+
+/**
+ * Casts a Drizzle nested-transaction handle to the shared database type.
+ *
+ * Drizzle types a nested transaction callback with the dialect's own
+ * transaction handle, which differs from `CartethyiaDatabase`. The cast is
+ * required (both drivers implement the surface stores use), but it is a type
+ * hole every time it appears raw — so it is centralized here rather than
+ * scattered across call sites.
+ */
+export function asConsoleDb(tx: unknown): CartethyiaDatabase {
+  return tx as unknown as CartethyiaDatabase;
+}

package/src/console/system-prompt/contracts.ts

@@ -16,33 +16,70 @@ export interface PromptSetting {
 export const PROMPT_MODES = ["append", "override"] as const;
 export type PromptMode = (typeof PROMPT_MODES)[number];
 
-/** Per-provider entry: follow the tenant's global prompt, or carry a custom one. */
-export interface ProviderPromptEntry {
-  readonly followGlobal: boolean;
-  /** Present and used only when `followGlobal` is false. */
-  readonly setting?: PromptSetting;
+/**
+ * A named, reusable prompt. Scopes reference presets by id instead of each
+ * carrying its own text, so one tone/ruleset can be applied to many scopes.
+ */
+export interface SystemPromptPreset {
+  readonly id: string;
+  readonly name: string;
+  readonly enabled: boolean;
+  readonly mode: PromptMode;
+  readonly text: string;
 }
 
+/**
+ * How one scope decides what to inject. Modes:
+ *
+ * - `off`    — explicitly inject nothing for this scope; scope-specific stop,
+ *              does NOT fall through to the global prompt.
+ * - `global`  — follow the tenant's global prompt (the default posture).
+ * - `preset`  — use the referenced named preset (disabled preset = no inject).
+ * - `custom`  — carry this scope's own prompt inline.
+ *
+ * A scope with no entry at all behaves as `global` (resolution falls through
+ * to the global prompt), so omitting a key is the same as an explicit
+ * `{ kind: "global" }` reference. The global scope itself never uses
+ * `{ kind: "global" }` — it is `null` (off), a preset, or a custom setting.
+ */
+export type ScopePromptRef =
+  | { readonly kind: "off" }
+  | { readonly kind: "global" }
+  | { readonly kind: "preset"; readonly presetId: string }
+  | { readonly kind: "custom"; readonly setting: PromptSetting };
+
 /** The full per-tenant configuration, one row in `tenant_system_prompts`. */
 export interface TenantSystemPrompts {
-  /** `null` = never configured — distinct from an explicit disabled setting. */
-  readonly global: PromptSetting | null;
-  /** providerId → entry */
-  readonly providers: Readonly<Record<string, ProviderPromptEntry>>;
-  /** `${providerId}::${modelId}` → setting */
-  readonly models: Readonly<Record<string, PromptSetting>>;
+  /** `null` = no global injection — distinct from an explicit disabled setting. */
+  readonly global: ScopePromptRef | null;
+  /** preset id → preset */
+  readonly presets: Readonly<Record<string, SystemPromptPreset>>;
+  /** providerId → ref */
+  readonly providers: Readonly<Record<string, ScopePromptRef>>;
+  /** `${providerId}::${modelId}` → ref */
+  readonly models: Readonly<Record<string, ScopePromptRef>>;
+  /** combo name → ref */
+  readonly combos: Readonly<Record<string, ScopePromptRef>>;
+  /** alias name → ref */
+  readonly aliases: Readonly<Record<string, ScopePromptRef>>;
 }
 
 /** Empty configuration: nothing configured anywhere. */
 export const EMPTY_TENANT_SYSTEM_PROMPTS: TenantSystemPrompts = {
   global: null,
+  presets: {},
   providers: {},
   models: {},
+  combos: {},
+  aliases: {},
 };
 
 /** Maximum stored text per scope (5 MB). Enforced at the console API. */
 export const SYSTEM_PROMPT_TEXT_CAP_BYTES = 5_000_000;
 
+/** Maximum stored preset-name length. Enforced at the console API. */
+export const SYSTEM_PROMPT_PRESET_NAME_CAP = 200;
+
 /**
  * Marker wrapping tenant text injected into a provider wire whose upstream
  * validates the system prompt as a channel identity (the buddy family). The
@@ -52,12 +89,21 @@ export const SYSTEM_PROMPT_TEXT_CAP_BYTES = 5_000_000;
 export const SYSTEM_PROMPT_WRAPPER_PREFIX = "<cartethyia:system-prompt>";
 export const SYSTEM_PROMPT_WRAPPER_SUFFIX = "</cartethyia:system-prompt>";
 
+/** Maximum number of presets stored for one tenant. */
+export const SYSTEM_PROMPT_PRESET_LIMIT = 64;
+
 /** Maximum number of per-provider entries stored for one tenant. */
 export const SYSTEM_PROMPT_PROVIDER_LIMIT = 256;
 
 /** Maximum number of per-model entries stored for one tenant. */
 export const SYSTEM_PROMPT_MODEL_LIMIT = 512;
 
+/** Maximum number of per-combo entries stored for one tenant. */
+export const SYSTEM_PROMPT_COMBO_LIMIT = 512;
+
+/** Maximum number of per-alias entries stored for one tenant. */
+export const SYSTEM_PROMPT_ALIAS_LIMIT = 512;
+
 /**
  * Providers whose upstream validates the fixed system prompt as a channel
  * identity. Their system turn must keep the fixed prompt as the opener, so
@@ -66,7 +112,7 @@ export const SYSTEM_PROMPT_MODEL_LIMIT = 512;
  * `override` mode is not honoured for these providers — it would strip the
  * identity and the upstream would refuse the request.
  */
-export const WRAPPED_INJECTION_PROVIDERS: ReadonlySet<string> = new Set([
+const WRAPPED_INJECTION_PROVIDERS: ReadonlySet<string> = new Set([
   "cb", // CodeBuddy International
   "cbcn", // CodeBuddy CN
   "workbuddy",
@@ -100,3 +146,34 @@ export function isPromptSetting(value: unknown): value is PromptSetting {
     typeof candidate.text === "string"
   );
 }
+
+/** True when the value is a well-formed preset (shape only, not size). */
+export function isSystemPromptPreset(value: unknown): value is SystemPromptPreset {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<SystemPromptPreset>;
+  return (
+    typeof candidate.id === "string" &&
+    candidate.id.length > 0 &&
+    typeof candidate.name === "string" &&
+    candidate.name.length > 0 &&
+    typeof candidate.enabled === "boolean" &&
+    typeof candidate.mode === "string" &&
+    (PROMPT_MODES as readonly string[]).includes(candidate.mode) &&
+    typeof candidate.text === "string"
+  );
+}
+
+/** True when the value is a well-formed scope reference (shape only). */
+export function isScopePromptRef(value: unknown): value is ScopePromptRef {
+  if (typeof value !== "object" || value === null) return false;
+  const kind = (value as { kind?: unknown }).kind;
+  if (kind === "off" || kind === "global") return true;
+  if (kind === "preset") {
+    const presetId = (value as { presetId?: unknown }).presetId;
+    return typeof presetId === "string" && presetId.length > 0;
+  }
+  if (kind === "custom") {
+    return isPromptSetting((value as { setting?: unknown }).setting);
+  }
+  return false;
+}