@hed-hog/core 0.0.387 → 0.0.390

package/src/ai-instruction/ai-instruction.service.ts

@@ -1,35 +1,100 @@
 import { PaginationDTO } from '@hed-hog/api-pagination';
 import { Prisma, PrismaService } from '@hed-hog/api-prisma';
 import {
+  ConflictException,
   forwardRef,
   Inject,
   Injectable,
   Logger,
   NotFoundException,
+  OnModuleDestroy,
   OnModuleInit,
+  UnprocessableEntityException,
 } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
 import { DeleteDTO } from '../dto/delete.dto';
+import { createRedisPubSub, type RedisPubSub } from '../redis/redis-pubsub';
+import {
+  type AiPromptDefinition,
+  getAiPromptDefinition,
+  listAiPromptDefinitions,
+} from './ai-prompt-registry';
+import { estimateTokens, renderTemplate, validateTemplate } from './ai-prompt-template.util';
 import { CreateAiInstructionDTO } from './dto/create-ai-instruction.dto';
+import { PreviewAiInstructionDTO } from './dto/preview-ai-instruction.dto';
 import { UpdateAiInstructionDTO } from './dto/update-ai-instruction.dto';
 import type {
   AiInstructionLayer,
+  AiInstructionListFilters,
   AiInstructionRecord,
 } from './types/ai-instruction.types';
 
-type CacheEntry = { content: string; fetchedAt: number };
-
+/**
+ * `record: null` is a negative cache entry — the slug/layer does not exist.
+ * Without it, every lookup for a missing slug hits the database on every
+ * request (task prompts are resolved on every LLM call).
+ */
+type CacheEntry = { record: AiInstructionRecord | null; fetchedAt: number; ttl: number };
+
+/**
+ * Cross-pod invalidation happens through Redis, with the database version check
+ * as backup. These TTLs are the last resort for when both are unavailable.
+ */
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-
-const FALLBACK_SYSTEM_PROMPT =
+const TASK_CACHE_TTL_MS = 60 * 1000;
+const NEGATIVE_CACHE_TTL_MS = 60 * 1000;
+
+/**
+ * An empty `slugs` list means "drop everything" — the database version path
+ * knows a change happened but not which prompts it touched.
+ */
+type AiInstructionInvalidationMessage = {
+  originInstanceId: string;
+  version: number;
+  slugs: string[];
+};
+
+/**
+ * Reuses the generic runtime-version table owned by the settings service. No
+ * column there is setting-specific, and the unique index on `scope` means a new
+ * scope needs no migration — the idempotent INSERT below creates its own row.
+ */
+const RUNTIME_STATE_SCOPE = 'ai_instruction';
+
+/**
+ * Columns are cast explicitly because `$queryRaw` returns DECIMAL as
+ * `Prisma.Decimal`, which serializes as a string over HTTP and becomes NaN in
+ * arithmetic. Keep every SELECT in this file using this list.
+ */
+const INSTRUCTION_COLUMNS = Prisma.sql`
+  id, slug, layer, name, content, variables_schema, locale, module_slug,
+  is_active, version, model, temperature::float8 AS temperature, max_tokens,
+  is_locked, created_at, updated_at
+`;
+
+export const FALLBACK_SYSTEM_PROMPT =
   'You are a helpful assistant with access to tools from the HedHog system. ' +
   "Use the available tools to answer the user's questions accurately. " +
   'Always respond in the same language the user writes in.';
 
 @Injectable()
-export class AiInstructionService implements OnModuleInit {
+export class AiInstructionService implements OnModuleInit, OnModuleDestroy {
   private readonly logger = new Logger(AiInstructionService.name);
   private readonly cache = new Map<string, CacheEntry>();
 
+  private readonly instanceId = randomUUID();
+  private readonly redisChannel = 'core:ai-instruction:invalidated';
+  private readonly versionCheckIntervalMs = Math.max(
+    1000,
+    Number(process.env.AI_INSTRUCTION_VERSION_CHECK_INTERVAL_MS || 5000),
+  );
+  private localCacheVersion = 0;
+  private lastVersionCheckAt = 0;
+  private versionCheckInFlight: Promise<void> | null = null;
+  private versionStateEnsured = false;
+  private lastVersionCheckErrorLogAt = 0;
+  private pubsub: RedisPubSub | null = null;
+
   constructor(
     @Inject(forwardRef(() => PrismaService))
     private readonly prisma: PrismaService,
@@ -38,10 +103,46 @@ export class AiInstructionService implements OnModuleInit {
   async onModuleInit() {
     // Warm up global and product layers on startup
     try {
+      // Before the warm-up: starting at version 0 would make the first read
+      // think it is behind and throw the freshly warmed cache away.
+      await this.syncCacheVersionFromDatabase();
       await this.getLayer('system');
       await this.getLayer('product');
+      await this.warnAboutUnseededPrompts();
     } catch {
-      // DB may not be ready yet; cache will fill on first request
+      // DB may not be ready yet; cache and version fill in on first request
+    }
+
+    // Outside the try: createRedisPubSub already handles its own failures.
+    this.pubsub = await createRedisPubSub({
+      channel: this.redisChannel,
+      logger: this.logger,
+      label: 'ai instruction',
+      onMessage: (raw) => this.handleInvalidationMessage(raw),
+    });
+  }
+
+  async onModuleDestroy() {
+    await this.pubsub?.close();
+  }
+
+  /**
+   * Reports prompts declared in code that have no row yet. Without this, a
+   * forgotten seed only surfaces the first time that AI flow runs — which for
+   * essay grading means the first graded exam.
+   */
+  private async warnAboutUnseededPrompts() {
+    const definitions = listAiPromptDefinitions();
+    if (!definitions.length) return;
+
+    const records = await this.getRecordsBySlugs(definitions.map((d) => d.slug));
+    const missing = definitions.filter((d) => !records.get(d.slug)).map((d) => d.slug);
+
+    if (missing.length) {
+      this.logger.warn(
+        `${missing.length} AI prompt(s) declared in code have no ai_instruction row ` +
+          `and will use the code fallback: ${missing.join(', ')}`,
+      );
     }
   }
 
@@ -50,70 +151,349 @@ export class AiInstructionService implements OnModuleInit {
   async getLayer(layer: AiInstructionLayer, moduleSlug?: string): Promise<string> {
     const cacheKey = moduleSlug ? `${layer}:${moduleSlug}` : layer;
 
-    const cached = this.cache.get(cacheKey);
-    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-      return cached.content;
+    await this.ensureCacheVersionFresh();
+
+    const cached = this.readCache(cacheKey);
+    if (cached !== undefined) {
+      return cached?.content ?? (layer === 'system' ? FALLBACK_SYSTEM_PROMPT : '');
     }
 
     const instruction = await this.findActiveByLayer(layer, moduleSlug);
+    this.writeCache(cacheKey, instruction);
+
     if (!instruction) {
-      if (layer === 'system') {
-        return FALLBACK_SYSTEM_PROMPT;
-      }
-      return '';
+      return layer === 'system' ? FALLBACK_SYSTEM_PROMPT : '';
     }
-
-    this.cache.set(cacheKey, { content: instruction.content, fetchedAt: Date.now() });
     return instruction.content;
   }
 
   async getAgentInstruction(agentSlug: string): Promise<string> {
     const cacheKey = `agent:${agentSlug}`;
-    const cached = this.cache.get(cacheKey);
-    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
-      return cached.content;
-    }
+
+    await this.ensureCacheVersionFresh();
+
+    const cached = this.readCache(cacheKey);
+    if (cached !== undefined) return cached?.content ?? '';
 
     const instruction = await this.findActiveBySlug(`agent.${agentSlug}`);
-    if (!instruction) return '';
+    this.writeCache(cacheKey, instruction);
 
-    this.cache.set(cacheKey, { content: instruction.content, fetchedAt: Date.now() });
-    return instruction.content;
+    return instruction?.content ?? '';
   }
 
-  invalidateCache(slug?: string) {
-    if (slug) {
-      // Cache keys use format "layer" or "layer:identifier"
-      // Slugs use format "layer.identifier" (e.g., "module.lms", "agent.admin-support")
-      const dotIndex = slug.indexOf('.');
-      if (dotIndex === -1) {
-        this.cache.delete(slug);
+  /**
+   * Full record by exact slug, cached. This is what `AiPromptResolverService`
+   * uses for task prompts — it needs the model params and `is_locked`, not just
+   * the content.
+   */
+  async getRecordBySlug(slug: string): Promise<AiInstructionRecord | null> {
+    const cacheKey = `slug:${slug}`;
+
+    await this.ensureCacheVersionFresh();
+
+    const cached = this.readCache(cacheKey);
+    if (cached !== undefined) return cached;
+
+    const record = await this.findBySlug(slug);
+    this.writeCache(cacheKey, record);
+
+    return record;
+  }
+
+  /** One query for pipelines that resolve several prompts per call. */
+  async getRecordsBySlugs(slugs: string[]): Promise<Map<string, AiInstructionRecord | null>> {
+    const result = new Map<string, AiInstructionRecord | null>();
+    const missing: string[] = [];
+
+    await this.ensureCacheVersionFresh();
+
+    for (const slug of slugs) {
+      const cached = this.readCache(`slug:${slug}`);
+      if (cached !== undefined) {
+        result.set(slug, cached);
       } else {
-        const layer = slug.slice(0, dotIndex);
-        const identifier = slug.slice(dotIndex + 1);
-        this.cache.delete(layer);
-        this.cache.delete(`${layer}:${identifier}`);
+        missing.push(slug);
       }
-    } else {
+    }
+
+    if (missing.length) {
+      const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
+        SELECT ${INSTRUCTION_COLUMNS}
+        FROM ai_instruction WHERE slug IN (${Prisma.join(missing)})
+      `);
+
+      const found = new Map(rows.map((row) => [row.slug, row]));
+      for (const slug of missing) {
+        const record = found.get(slug) || null;
+        this.writeCache(`slug:${slug}`, record);
+        result.set(slug, record);
+      }
+    }
+
+    return result;
+  }
+
+  invalidateCache(slug?: string) {
+    if (!slug) {
       this.cache.clear();
+      return;
+    }
+
+    // Exact-slug key used by getRecordBySlug/getRecordsBySlugs.
+    this.cache.delete(`slug:${slug}`);
+
+    // Layer keys use format "layer" or "layer:identifier", while slugs use
+    // "layer.identifier" (e.g. "module.lms", "agent.admin-support").
+    const dotIndex = slug.indexOf('.');
+    if (dotIndex === -1) {
+      this.cache.delete(slug);
+    } else {
+      const layer = slug.slice(0, dotIndex);
+      const identifier = slug.slice(dotIndex + 1);
+      this.cache.delete(layer);
+      this.cache.delete(`${layer}:${identifier}`);
+    }
+  }
+
+  /** `undefined` = cache miss/expired. `null` = cached absence. */
+  private readCache(cacheKey: string): AiInstructionRecord | null | undefined {
+    const cached = this.cache.get(cacheKey);
+    if (!cached) return undefined;
+    if (Date.now() - cached.fetchedAt >= cached.ttl) {
+      this.cache.delete(cacheKey);
+      return undefined;
+    }
+    return cached.record;
+  }
+
+  private writeCache(cacheKey: string, record: AiInstructionRecord | null) {
+    const ttl = !record
+      ? NEGATIVE_CACHE_TTL_MS
+      : record.layer === 'task'
+        ? TASK_CACHE_TTL_MS
+        : CACHE_TTL_MS;
+
+    this.cache.set(cacheKey, { record, fetchedAt: Date.now(), ttl });
+  }
+
+  // ── Cross-pod invalidation ───────────────────────────────────────────────
+
+  private handleInvalidationMessage(raw: string) {
+    let payload: AiInstructionInvalidationMessage;
+
+    try {
+      payload = JSON.parse(raw) as AiInstructionInvalidationMessage;
+    } catch {
+      return;
+    }
+
+    if (!payload || payload.originInstanceId === this.instanceId) {
+      return;
+    }
+
+    // The version is only a watermark, so the lazy check does not re-clear a
+    // cache this message already fixed selectively. The invalidation itself is
+    // applied unconditionally: dropping an out-of-order message — this pod may
+    // have bumped past it on a write of its own — would leave the slug stale
+    // here until its TTL, which is exactly the bug this whole path fixes.
+    if (Number.isFinite(payload.version)) {
+      this.localCacheVersion = Math.max(this.localCacheVersion, payload.version);
+      this.lastVersionCheckAt = Date.now();
+    }
+
+    const slugs = Array.isArray(payload.slugs) ? payload.slugs.filter(Boolean) : [];
+    if (!slugs.length) {
+      this.invalidateCache();
+      return;
+    }
+
+    for (const slug of slugs) {
+      this.invalidateCache(slug);
+    }
+  }
+
+  private async ensureVersionState() {
+    // The row is created once and never removed; repeating the INSERT on every
+    // version check would double the queries of a path that runs every 5s.
+    if (this.versionStateEnsured) {
+      return;
+    }
+
+    await this.prisma.$executeRawUnsafe(`
+      INSERT INTO "setting_runtime_state" ("scope", "version", "updated_at")
+      VALUES ('${RUNTIME_STATE_SCOPE}', 0, NOW())
+      ON CONFLICT ("scope") DO NOTHING
+    `);
+    this.versionStateEnsured = true;
+  }
+
+  /** BIGINT comes back from `$queryRawUnsafe` as a `bigint`, not a number. */
+  private parseVersionValue(value: unknown): number {
+    if (typeof value === 'number') {
+      return value;
+    }
+
+    if (typeof value === 'bigint') {
+      return Number(value);
+    }
+
+    if (typeof value === 'string') {
+      return Number(value);
+    }
+
+    return 0;
+  }
+
+  private async getCacheVersionFromDatabase(): Promise<number> {
+    await this.ensureVersionState();
+
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ version: unknown }>>(`
+      SELECT "version"
+      FROM "setting_runtime_state"
+      WHERE "scope" = '${RUNTIME_STATE_SCOPE}'
+      LIMIT 1
+    `);
+
+    return this.parseVersionValue(rows[0]?.version);
+  }
+
+  private async syncCacheVersionFromDatabase() {
+    this.localCacheVersion = await this.getCacheVersionFromDatabase();
+    this.lastVersionCheckAt = Date.now();
+  }
+
+  private async bumpCacheVersion(): Promise<number> {
+    await this.ensureVersionState();
+
+    const rows = await this.prisma.$queryRawUnsafe<Array<{ version: unknown }>>(`
+      UPDATE "setting_runtime_state"
+      SET "version" = "version" + 1,
+          "updated_at" = NOW()
+      WHERE "scope" = '${RUNTIME_STATE_SCOPE}'
+      RETURNING "version"
+    `);
+
+    const nextVersion = this.parseVersionValue(rows[0]?.version);
+    this.localCacheVersion = nextVersion;
+    this.lastVersionCheckAt = Date.now();
+    return nextVersion;
+  }
+
+  /**
+   * Catches up with writes from other pods when Redis is unavailable. Throttled
+   * and coalesced, so a burst of prompt resolutions costs one query at most.
+   */
+  private async ensureCacheVersionFresh() {
+    const now = Date.now();
+    if (now - this.lastVersionCheckAt < this.versionCheckIntervalMs) {
+      return;
+    }
+
+    // `lastVersionCheckAt` only advances after the await, so parallel reads
+    // would each fire the same query and tie up the connection pool.
+    if (this.versionCheckInFlight) {
+      return this.versionCheckInFlight;
+    }
+
+    this.versionCheckInFlight = this.runVersionCheck(now).finally(() => {
+      this.versionCheckInFlight = null;
+    });
+
+    return this.versionCheckInFlight;
+  }
+
+  private async runVersionCheck(startedAt: number) {
+    try {
+      const currentVersion = await this.getCacheVersionFromDatabase();
+      this.lastVersionCheckAt = startedAt;
+
+      if (currentVersion > this.localCacheVersion) {
+        this.localCacheVersion = currentVersion;
+        // This path knows a change happened but not which slugs it touched.
+        this.cache.clear();
+      }
+    } catch (error) {
+      // Bookkeeping must never break prompt resolution: the resolver handles a
+      // throw by falling back to the code prompt, so a slow database would
+      // silently downgrade prompt quality. Serving the current cache is better.
+      this.lastVersionCheckAt = startedAt; // and do not hammer a sick database
+      this.logVersionCheckError(error);
+    }
+  }
+
+  private logVersionCheckError(error: unknown) {
+    const now = Date.now();
+    if (now - this.lastVersionCheckErrorLogAt < 30000) {
+      return;
+    }
+    this.lastVersionCheckErrorLogAt = now;
+    this.logger.warn(
+      `Failed to check ai instruction cache version: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  /**
+   * Tells the other pods to drop these slugs. Bumps the database version first
+   * so pods without Redis still catch up on their next version check.
+   */
+  private async publishInvalidation(slugs: string[]) {
+    const filteredSlugs = Array.from(new Set(slugs.filter(Boolean)));
+    if (filteredSlugs.length === 0) {
+      return;
+    }
+
+    let version = this.localCacheVersion;
+
+    try {
+      version = await this.bumpCacheVersion();
+    } catch (error) {
+      // The prompt write already committed; failing here must not turn a
+      // successful edit into a 500.
+      this.logger.warn(
+        `Failed to bump ai instruction cache version: ${error instanceof Error ? error.message : String(error)}`,
+      );
     }
+
+    // A stale version here is harmless: receivers take the max, and the lazy
+    // check compares against the database, not against this number.
+    await this.pubsub?.publish({
+      originInstanceId: this.instanceId,
+      version,
+      slugs: filteredSlugs,
+    } satisfies AiInstructionInvalidationMessage);
   }
 
   // ── CRUD ─────────────────────────────────────────────────────────────────
 
-  async list(paginationParams: PaginationDTO) {
+  async list(paginationParams: PaginationDTO, filters?: AiInstructionListFilters) {
     const page = Math.max(Number(paginationParams?.page || 1), 1);
     const pageSize = Math.min(Math.max(Number(paginationParams?.pageSize || 20), 1), 100);
     const offset = (page - 1) * pageSize;
     const search = String(paginationParams?.search || '').trim();
 
-    const whereClause = search
-      ? Prisma.sql`WHERE (LOWER(slug) LIKE LOWER(${`%${search}%`}) OR LOWER(name) LIKE LOWER(${`%${search}%`}))`
+    const conditions: Prisma.Sql[] = [];
+
+    if (search) {
+      conditions.push(
+        Prisma.sql`(LOWER(slug) LIKE LOWER(${`%${search}%`}) OR LOWER(name) LIKE LOWER(${`%${search}%`}))`,
+      );
+    }
+    if (filters?.layer) {
+      conditions.push(Prisma.sql`layer = CAST(${filters.layer} AS ai_instruction_layer_enum)`);
+    }
+    if (filters?.module_slug) {
+      conditions.push(Prisma.sql`module_slug = ${filters.module_slug}`);
+    }
+    if (filters?.is_active !== undefined) {
+      conditions.push(Prisma.sql`is_active = ${filters.is_active}`);
+    }
+
+    const whereClause = conditions.length
+      ? Prisma.sql`WHERE ${Prisma.join(conditions, ' AND ')}`
       : Prisma.empty;
 
     const data = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+      SELECT ${INSTRUCTION_COLUMNS}
       FROM ai_instruction
       ${whereClause}
       ORDER BY layer, slug
@@ -136,14 +516,95 @@ export class AiInstructionService implements OnModuleInit {
     };
   }
 
+  /** Distinct module slugs, for the module filter in the admin. */
+  async listModules(): Promise<string[]> {
+    const rows = await this.prisma.$queryRaw<Array<{ module_slug: string }>>(Prisma.sql`
+      SELECT DISTINCT module_slug FROM ai_instruction
+      WHERE module_slug IS NOT NULL
+      ORDER BY module_slug
+    `);
+    return rows.map((row) => row.module_slug);
+  }
+
+  /**
+   * The prompts declared in code, paired with what the database currently holds.
+   *
+   * `dbMatchesFallback` is what lets the admin show "default" vs "customized"
+   * and offer "restore default"; it is also the fidelity check after a seed —
+   * every freshly seeded prompt must report `true`.
+   */
+  async listRegistry(moduleSlug?: string) {
+    const definitions = listAiPromptDefinitions(moduleSlug);
+    const records = await this.getRecordsBySlugs(definitions.map((d) => d.slug));
+
+    return definitions.map((definition) => {
+      const record = records.get(definition.slug) || null;
+
+      return {
+        slug: definition.slug,
+        name: definition.name,
+        module_slug: definition.moduleSlug,
+        locale: definition.locale || 'pt',
+        fallback: definition.fallback,
+        variables: definition.variables,
+        security_sensitive: Boolean(definition.securitySensitive),
+        required_phrases: definition.requiredPhrases || [],
+        defaults: definition.defaults || {},
+        exists_in_db: Boolean(record),
+        db_matches_fallback: record ? record.content === definition.fallback : false,
+      };
+    });
+  }
+
+  /** Renders a draft without saving it, so the admin can check interpolation. */
+  previewPrompt(input: PreviewAiInstructionDTO) {
+    const definition = input.slug ? getAiPromptDefinition(input.slug) : undefined;
+    const schema = definition?.variables ?? input.variables_schema ?? null;
+    const validation = validateTemplate(input.content, schema);
+
+    let rendered = '';
+    let renderError: string | null = null;
+    try {
+      rendered = renderTemplate(input.content, input.variables || {});
+    } catch (error) {
+      renderError = error instanceof Error ? error.message : String(error);
+    }
+
+    const warnings: string[] = [];
+    if (validation.unknownPlaceholders.length) {
+      warnings.push(
+        `Variáveis não declaradas: ${validation.unknownPlaceholders.join(', ')}. ` +
+          'Elas serão renderizadas literalmente.',
+      );
+    }
+    warnings.push(...this.missingPhraseWarnings(definition, input.content));
+
+    return {
+      rendered,
+      render_error: renderError,
+      char_count: rendered.length,
+      estimated_tokens: estimateTokens(rendered),
+      missing_required: validation.missingRequired,
+      unknown_placeholders: validation.unknownPlaceholders,
+      unbalanced_blocks: validation.unbalancedBlocks,
+      warnings,
+    };
+  }
+
   async getById(id: number): Promise<AiInstructionRecord> {
     const record = await this.findById(id);
     if (!record) throw new NotFoundException(`AI instruction ${id} not found.`);
     return record;
   }
 
-  async getBySlug(slug: string): Promise<AiInstructionRecord> {
-    const record = await this.findActiveBySlug(slug);
+  /**
+   * Inactive records are returned on purpose: the admin needs to open one to
+   * reactivate it. Pass `activeOnly` for the resolution path.
+   */
+  async getBySlug(slug: string, activeOnly = false): Promise<AiInstructionRecord> {
+    const record = activeOnly
+      ? await this.findActiveBySlug(slug)
+      : await this.findBySlug(slug);
     if (!record) throw new NotFoundException(`AI instruction "${slug}" not found.`);
     return record;
   }
@@ -152,8 +613,18 @@ export class AiInstructionService implements OnModuleInit {
     const locale = dto.locale || 'en';
     const isActive = dto.is_active ?? true;
 
+    const existing = await this.findBySlug(dto.slug);
+    if (existing) {
+      throw new ConflictException(`AI instruction "${dto.slug}" already exists.`);
+    }
+
+    this.validateContent(dto.slug, dto.content, {
+      fallbackSchema: dto.variables_schema ?? null,
+      allowMissingVariables: dto.allow_missing_variables,
+    });
+
     await this.prisma.$executeRaw`
-      INSERT INTO ai_instruction (slug, layer, name, content, variables_schema, locale, module_slug, is_active, version)
+      INSERT INTO ai_instruction (slug, layer, name, content, variables_schema, locale, module_slug, is_active, version, model, temperature, max_tokens)
       VALUES (
         ${dto.slug},
         CAST(${dto.layer} AS ai_instruction_layer_enum),
@@ -163,28 +634,61 @@ export class AiInstructionService implements OnModuleInit {
         ${locale},
         ${dto.module_slug || null},
         ${isActive},
-        1
+        1,
+        ${dto.model ?? null},
+        ${dto.temperature ?? null},
+        ${dto.max_tokens ?? null}
       )
     `;
 
-    const created = await this.findActiveBySlug(dto.slug);
+    const created = await this.findBySlug(dto.slug);
 
     // Record version 1
     if (created) {
       await this.saveVersion(created.id, 1, dto.content, 'Initial version', createdById);
     }
 
+    // Negative cache entries for this slug must go, otherwise the prompt stays
+    // invisible to the resolver until the TTL expires. Kept separate from the
+    // publish below so a Redis outage never leaves this pod itself stale.
+    this.invalidateCache(dto.slug);
+    await this.publishInvalidation([dto.slug]);
+
     return created;
   }
 
   async update(id: number, dto: UpdateAiInstructionDTO, updatedById?: number) {
     const current = await this.getById(id);
 
+    // Locked records are security-sensitive prompts (the essay-grading
+    // injection defence). Still editable, but never by accident.
+    if (current.is_locked && !dto.acknowledge_security_review) {
+      throw new ConflictException(
+        `AI instruction "${current.slug}" is a security-sensitive prompt. ` +
+          'Send acknowledge_security_review=true to confirm you reviewed the change.',
+      );
+    }
+
     const newContent = dto.content ?? current.content;
     const newVersion = dto.content && dto.content !== current.content
       ? current.version + 1
       : current.version;
 
+    const warnings = dto.content !== undefined
+      ? this.validateContent(current.slug, dto.content, {
+          fallbackSchema: current.variables_schema,
+          allowMissingVariables: dto.allow_missing_variables,
+        })
+      : [];
+
+    // Losing every guard phrase is recorded in the immutable version row, not
+    // just in the log — the resolver will also refuse the stored copy.
+    const changeNote = warnings.length
+      ? [dto.change_note, `[warnings: ${warnings.join(' | ')}]`].filter(Boolean).join(' ').slice(0, 500)
+      : dto.change_note;
+
+    // `undefined` means "leave alone", `null` means "clear" — `??` collapses the
+    // two, so the model params use an explicit undefined check.
     await this.prisma.$executeRaw`
       UPDATE ai_instruction
       SET
@@ -194,6 +698,9 @@ export class AiInstructionService implements OnModuleInit {
         locale           = ${dto.locale ?? current.locale},
         module_slug      = ${dto.module_slug !== undefined ? dto.module_slug : current.module_slug},
         is_active        = ${dto.is_active ?? current.is_active},
+        model            = ${dto.model !== undefined ? dto.model : current.model},
+        temperature      = ${dto.temperature !== undefined ? dto.temperature : current.temperature},
+        max_tokens       = ${dto.max_tokens !== undefined ? dto.max_tokens : current.max_tokens},
         version          = ${newVersion},
         updated_at       = NOW()
       WHERE id = ${id}
@@ -201,12 +708,13 @@ export class AiInstructionService implements OnModuleInit {
 
     // Save new version if content changed
     if (dto.content && dto.content !== current.content) {
-      await this.saveVersion(id, newVersion, newContent, dto.change_note, updatedById);
+      await this.saveVersion(id, newVersion, newContent, changeNote, updatedById);
     }
 
     this.invalidateCache(current.slug);
+    await this.publishInvalidation([current.slug]);
 
-    return this.getById(id);
+    return { ...(await this.getById(id)), warnings };
   }
 
   async delete({ ids }: DeleteDTO) {
@@ -224,6 +732,8 @@ export class AiInstructionService implements OnModuleInit {
     `;
 
     existing.forEach((r) => this.invalidateCache(r.slug));
+    // One bump and one message for the whole batch.
+    await this.publishInvalidation(existing.map((r) => r.slug));
 
     return { count: ids.length };
   }
@@ -270,27 +780,116 @@ export class AiInstructionService implements OnModuleInit {
     );
 
     this.invalidateCache(current.slug);
+    await this.publishInvalidation([current.slug]);
 
     return this.getById(id);
   }
 
   // ── Private helpers ───────────────────────────────────────────────────────
 
+  /**
+   * Rejects content that would break at render time, and returns non-fatal
+   * warnings for the caller to surface.
+   *
+   * An unclosed block is a hard 422: it silently swallows the rest of the
+   * prompt. A removed required variable is also a 422, overridable with
+   * `allow_missing_variables` — sometimes a rewrite genuinely no longer needs a
+   * variable. An unknown placeholder is only a warning: it renders literally,
+   * which is ugly but harmless.
+   */
+  private validateContent(
+    slug: string,
+    content: string,
+    options: {
+      fallbackSchema?: Record<string, any> | null;
+      allowMissingVariables?: boolean;
+    },
+  ): string[] {
+    const definition = getAiPromptDefinition(slug);
+    const schema = definition?.variables ?? options.fallbackSchema ?? null;
+    const { missingRequired, unknownPlaceholders, unbalancedBlocks } = validateTemplate(
+      content,
+      schema,
+    );
+
+    if (unbalancedBlocks.length) {
+      throw new UnprocessableEntityException(
+        `Bloco de template não fechado: ${unbalancedBlocks
+          .map((name) => `{{#${name}}}`)
+          .join(', ')}. Isso descartaria o resto do prompt.`,
+      );
+    }
+
+    if (missingRequired.length && !options.allowMissingVariables) {
+      throw new UnprocessableEntityException(
+        `Variáveis obrigatórias ausentes do conteúdo: ${missingRequired.join(', ')}. ` +
+          'Envie allow_missing_variables=true para salvar mesmo assim.',
+      );
+    }
+
+    const warnings: string[] = [];
+    if (missingRequired.length) {
+      warnings.push(`missing-variables: ${missingRequired.join(', ')}`);
+    }
+    if (unknownPlaceholders.length) {
+      warnings.push(`unknown-variables: ${unknownPlaceholders.join(', ')}`);
+    }
+    warnings.push(...this.missingPhraseWarnings(definition, content));
+
+    return warnings;
+  }
+
+  /**
+   * Guard phrases are the runtime protection for security-sensitive prompts: if
+   * the stored content contains none of them, `AiPromptResolverService` discards
+   * it. Warn loudly here so the editor learns it before the first graded essay.
+   */
+  private missingPhraseWarnings(
+    definition: AiPromptDefinition | undefined,
+    content: string,
+  ): string[] {
+    const phrases = definition?.requiredPhrases;
+    if (!phrases?.length) return [];
+
+    const missing = phrases.filter((phrase) => !content.includes(phrase));
+    if (!missing.length) return [];
+
+    const hasAny = missing.length < phrases.length;
+    const warning = `security-phrases-removed: ${missing.join(', ')}`;
+
+    if (hasAny) {
+      this.logger.warn(`AI prompt "${definition!.slug}" lost safety phrases: ${missing.join(', ')}`);
+      return [warning];
+    }
+
+    this.logger.error(
+      `AI prompt "${definition!.slug}" lost ALL of its safety phrases; the resolver ` +
+        'will ignore the stored content and use the code fallback.',
+    );
+    return [`${warning} (todas — o prompt do banco será ignorado em runtime)`];
+  }
+
   private async findById(id: number): Promise<AiInstructionRecord | null> {
-    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>`
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
+      SELECT ${INSTRUCTION_COLUMNS}
       FROM ai_instruction WHERE id = ${id} LIMIT 1
-    `;
+    `);
+    return rows?.[0] || null;
+  }
+
+  private async findBySlug(slug: string): Promise<AiInstructionRecord | null> {
+    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
+      SELECT ${INSTRUCTION_COLUMNS}
+      FROM ai_instruction WHERE slug = ${slug} LIMIT 1
+    `);
     return rows?.[0] || null;
   }
 
   private async findActiveBySlug(slug: string): Promise<AiInstructionRecord | null> {
-    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>`
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
+      SELECT ${INSTRUCTION_COLUMNS}
       FROM ai_instruction WHERE slug = ${slug} AND is_active = TRUE LIMIT 1
-    `;
+    `);
     return rows?.[0] || null;
   }
 
@@ -299,27 +898,27 @@ export class AiInstructionService implements OnModuleInit {
     moduleSlug?: string,
   ): Promise<AiInstructionRecord | null> {
     if (moduleSlug) {
-      const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>`
-        SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-               is_active, version, created_at, updated_at
+      const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
+        SELECT ${INSTRUCTION_COLUMNS}
         FROM ai_instruction
         WHERE layer = CAST(${layer} AS ai_instruction_layer_enum)
           AND module_slug = ${moduleSlug}
           AND is_active = TRUE
+        ORDER BY id
         LIMIT 1
-      `;
+      `);
       if (rows?.[0]) return rows[0];
     }
 
-    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>`
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+    const rows = await this.prisma.$queryRaw<AiInstructionRecord[]>(Prisma.sql`
+      SELECT ${INSTRUCTION_COLUMNS}
       FROM ai_instruction
       WHERE layer = CAST(${layer} AS ai_instruction_layer_enum)
         AND module_slug IS NULL
         AND is_active = TRUE
+      ORDER BY id
       LIMIT 1
-    `;
+    `);
     return rows?.[0] || null;
   }