@hed-hog/core 0.0.387 → 0.0.390

package/dist/ai-instruction/ai-instruction.service.js

@@ -13,11 +13,37 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 var AiInstructionService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiInstructionService = void 0;
+exports.AiInstructionService = exports.FALLBACK_SYSTEM_PROMPT = void 0;
 const api_prisma_1 = require("@hed-hog/api-prisma");
 const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const redis_pubsub_1 = require("../redis/redis-pubsub");
+const ai_prompt_registry_1 = require("./ai-prompt-registry");
+const ai_prompt_template_util_1 = require("./ai-prompt-template.util");
+/**
+ * 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 = 'You are a helpful assistant with access to tools from the HedHog system. ' +
+const TASK_CACHE_TTL_MS = 60 * 1000;
+const NEGATIVE_CACHE_TTL_MS = 60 * 1000;
+/**
+ * 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 = api_prisma_1.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
+`;
+exports.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.';
 let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
@@ -25,78 +51,349 @@ let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
         this.prisma = prisma;
         this.logger = new common_1.Logger(AiInstructionService_1.name);
         this.cache = new Map();
+        this.instanceId = (0, node_crypto_1.randomUUID)();
+        this.redisChannel = 'core:ai-instruction:invalidated';
+        this.versionCheckIntervalMs = Math.max(1000, Number(process.env.AI_INSTRUCTION_VERSION_CHECK_INTERVAL_MS || 5000));
+        this.localCacheVersion = 0;
+        this.lastVersionCheckAt = 0;
+        this.versionCheckInFlight = null;
+        this.versionStateEnsured = false;
+        this.lastVersionCheckErrorLogAt = 0;
+        this.pubsub = null;
     }
     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 (_a) {
-            // 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 (0, redis_pubsub_1.createRedisPubSub)({
+            channel: this.redisChannel,
+            logger: this.logger,
+            label: 'ai instruction',
+            onMessage: (raw) => this.handleInvalidationMessage(raw),
+        });
+    }
+    async onModuleDestroy() {
+        var _a;
+        await ((_a = this.pubsub) === null || _a === void 0 ? void 0 : _a.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.
+     */
+    async warnAboutUnseededPrompts() {
+        const definitions = (0, ai_prompt_registry_1.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(', ')}`);
         }
     }
     // ── Public layer accessors (cached) ──────────────────────────────────────
     async getLayer(layer, moduleSlug) {
+        var _a;
         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 (_a = cached === null || cached === void 0 ? void 0 : cached.content) !== null && _a !== void 0 ? _a : (layer === 'system' ? exports.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' ? exports.FALLBACK_SYSTEM_PROMPT : '';
         }
-        this.cache.set(cacheKey, { content: instruction.content, fetchedAt: Date.now() });
         return instruction.content;
     }
     async getAgentInstruction(agentSlug) {
+        var _a, _b;
         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 (_a = cached === null || cached === void 0 ? void 0 : cached.content) !== null && _a !== void 0 ? _a : '';
         const instruction = await this.findActiveBySlug(`agent.${agentSlug}`);
-        if (!instruction)
-            return '';
-        this.cache.set(cacheKey, { content: instruction.content, fetchedAt: Date.now() });
-        return instruction.content;
+        this.writeCache(cacheKey, instruction);
+        return (_b = instruction === null || instruction === void 0 ? void 0 : instruction.content) !== null && _b !== void 0 ? _b : '';
     }
-    invalidateCache(slug) {
-        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) {
+        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) {
+        const result = new Map();
+        const missing = [];
+        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(api_prisma_1.Prisma.sql `
+        SELECT ${INSTRUCTION_COLUMNS}
+        FROM ai_instruction WHERE slug IN (${api_prisma_1.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) {
+        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. */
+    readCache(cacheKey) {
+        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;
+    }
+    writeCache(cacheKey, record) {
+        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 ───────────────────────────────────────────────
+    handleInvalidationMessage(raw) {
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch (_a) {
+            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);
+        }
+    }
+    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. */
+    parseVersionValue(value) {
+        if (typeof value === 'number') {
+            return value;
+        }
+        if (typeof value === 'bigint') {
+            return Number(value);
+        }
+        if (typeof value === 'string') {
+            return Number(value);
+        }
+        return 0;
+    }
+    async getCacheVersionFromDatabase() {
+        var _a;
+        await this.ensureVersionState();
+        const rows = await this.prisma.$queryRawUnsafe(`
+      SELECT "version"
+      FROM "setting_runtime_state"
+      WHERE "scope" = '${RUNTIME_STATE_SCOPE}'
+      LIMIT 1
+    `);
+        return this.parseVersionValue((_a = rows[0]) === null || _a === void 0 ? void 0 : _a.version);
+    }
+    async syncCacheVersionFromDatabase() {
+        this.localCacheVersion = await this.getCacheVersionFromDatabase();
+        this.lastVersionCheckAt = Date.now();
+    }
+    async bumpCacheVersion() {
+        var _a;
+        await this.ensureVersionState();
+        const rows = await this.prisma.$queryRawUnsafe(`
+      UPDATE "setting_runtime_state"
+      SET "version" = "version" + 1,
+          "updated_at" = NOW()
+      WHERE "scope" = '${RUNTIME_STATE_SCOPE}'
+      RETURNING "version"
+    `);
+        const nextVersion = this.parseVersionValue((_a = rows[0]) === null || _a === void 0 ? void 0 : _a.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.
+     */
+    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;
+    }
+    async runVersionCheck(startedAt) {
+        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);
         }
     }
+    logVersionCheckError(error) {
+        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.
+     */
+    async publishInvalidation(slugs) {
+        var _a;
+        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 ((_a = this.pubsub) === null || _a === void 0 ? void 0 : _a.publish({
+            originInstanceId: this.instanceId,
+            version,
+            slugs: filteredSlugs,
+        }));
+    }
     // ── CRUD ─────────────────────────────────────────────────────────────────
-    async list(paginationParams) {
+    async list(paginationParams, filters) {
         var _a;
         const page = Math.max(Number((paginationParams === null || paginationParams === void 0 ? void 0 : paginationParams.page) || 1), 1);
         const pageSize = Math.min(Math.max(Number((paginationParams === null || paginationParams === void 0 ? void 0 : paginationParams.pageSize) || 20), 1), 100);
         const offset = (page - 1) * pageSize;
         const search = String((paginationParams === null || paginationParams === void 0 ? void 0 : paginationParams.search) || '').trim();
-        const whereClause = search
-            ? api_prisma_1.Prisma.sql `WHERE (LOWER(slug) LIKE LOWER(${`%${search}%`}) OR LOWER(name) LIKE LOWER(${`%${search}%`}))`
+        const conditions = [];
+        if (search) {
+            conditions.push(api_prisma_1.Prisma.sql `(LOWER(slug) LIKE LOWER(${`%${search}%`}) OR LOWER(name) LIKE LOWER(${`%${search}%`}))`);
+        }
+        if (filters === null || filters === void 0 ? void 0 : filters.layer) {
+            conditions.push(api_prisma_1.Prisma.sql `layer = CAST(${filters.layer} AS ai_instruction_layer_enum)`);
+        }
+        if (filters === null || filters === void 0 ? void 0 : filters.module_slug) {
+            conditions.push(api_prisma_1.Prisma.sql `module_slug = ${filters.module_slug}`);
+        }
+        if ((filters === null || filters === void 0 ? void 0 : filters.is_active) !== undefined) {
+            conditions.push(api_prisma_1.Prisma.sql `is_active = ${filters.is_active}`);
+        }
+        const whereClause = conditions.length
+            ? api_prisma_1.Prisma.sql `WHERE ${api_prisma_1.Prisma.join(conditions, ' AND ')}`
             : api_prisma_1.Prisma.empty;
         const data = await this.prisma.$queryRaw(api_prisma_1.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
@@ -115,24 +412,105 @@ let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
             totalPages: Math.ceil(total / pageSize),
         };
     }
+    /** Distinct module slugs, for the module filter in the admin. */
+    async listModules() {
+        const rows = await this.prisma.$queryRaw(api_prisma_1.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) {
+        const definitions = (0, ai_prompt_registry_1.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) {
+        var _a, _b;
+        const definition = input.slug ? (0, ai_prompt_registry_1.getAiPromptDefinition)(input.slug) : undefined;
+        const schema = (_b = (_a = definition === null || definition === void 0 ? void 0 : definition.variables) !== null && _a !== void 0 ? _a : input.variables_schema) !== null && _b !== void 0 ? _b : null;
+        const validation = (0, ai_prompt_template_util_1.validateTemplate)(input.content, schema);
+        let rendered = '';
+        let renderError = null;
+        try {
+            rendered = (0, ai_prompt_template_util_1.renderTemplate)(input.content, input.variables || {});
+        }
+        catch (error) {
+            renderError = error instanceof Error ? error.message : String(error);
+        }
+        const warnings = [];
+        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: (0, ai_prompt_template_util_1.estimateTokens)(rendered),
+            missing_required: validation.missingRequired,
+            unknown_placeholders: validation.unknownPlaceholders,
+            unbalanced_blocks: validation.unbalancedBlocks,
+            warnings,
+        };
+    }
     async getById(id) {
         const record = await this.findById(id);
         if (!record)
             throw new common_1.NotFoundException(`AI instruction ${id} not found.`);
         return record;
     }
-    async getBySlug(slug) {
-        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, activeOnly = false) {
+        const record = activeOnly
+            ? await this.findActiveBySlug(slug)
+            : await this.findBySlug(slug);
         if (!record)
             throw new common_1.NotFoundException(`AI instruction "${slug}" not found.`);
         return record;
     }
     async create(dto, createdById) {
-        var _a;
+        var _a, _b, _c, _d, _e;
         const locale = dto.locale || 'en';
         const isActive = (_a = dto.is_active) !== null && _a !== void 0 ? _a : true;
+        const existing = await this.findBySlug(dto.slug);
+        if (existing) {
+            throw new common_1.ConflictException(`AI instruction "${dto.slug}" already exists.`);
+        }
+        this.validateContent(dto.slug, dto.content, {
+            fallbackSchema: (_b = dto.variables_schema) !== null && _b !== void 0 ? _b : 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),
@@ -142,23 +520,50 @@ let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
         ${locale},
         ${dto.module_slug || null},
         ${isActive},
-        1
+        1,
+        ${(_c = dto.model) !== null && _c !== void 0 ? _c : null},
+        ${(_d = dto.temperature) !== null && _d !== void 0 ? _d : null},
+        ${(_e = dto.max_tokens) !== null && _e !== void 0 ? _e : 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, dto, updatedById) {
         var _a, _b, _c, _d;
         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 common_1.ConflictException(`AI instruction "${current.slug}" is a security-sensitive prompt. ` +
+                'Send acknowledge_security_review=true to confirm you reviewed the change.');
+        }
         const newContent = (_a = dto.content) !== null && _a !== void 0 ? _a : 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
@@ -168,16 +573,20 @@ let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
         locale           = ${(_c = dto.locale) !== null && _c !== void 0 ? _c : current.locale},
         module_slug      = ${dto.module_slug !== undefined ? dto.module_slug : current.module_slug},
         is_active        = ${(_d = dto.is_active) !== null && _d !== void 0 ? _d : 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}
     `;
         // 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);
-        return this.getById(id);
+        await this.publishInvalidation([current.slug]);
+        return Object.assign(Object.assign({}, (await this.getById(id))), { warnings });
     }
     async delete({ ids }) {
         const existing = await this.prisma.$queryRaw(api_prisma_1.Prisma.sql `
@@ -191,6 +600,8 @@ let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
       DELETE FROM ai_instruction WHERE id IN (${api_prisma_1.Prisma.join(ids)})
     `;
         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 };
     }
     async listVersions(id) {
@@ -223,48 +634,110 @@ let AiInstructionService = AiInstructionService_1 = class AiInstructionService {
     `;
         await this.saveVersion(id, newVersion, target.content, `Restored from version ${version}`, restoredById);
         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.
+     */
+    validateContent(slug, content, options) {
+        var _a, _b;
+        const definition = (0, ai_prompt_registry_1.getAiPromptDefinition)(slug);
+        const schema = (_b = (_a = definition === null || definition === void 0 ? void 0 : definition.variables) !== null && _a !== void 0 ? _a : options.fallbackSchema) !== null && _b !== void 0 ? _b : null;
+        const { missingRequired, unknownPlaceholders, unbalancedBlocks } = (0, ai_prompt_template_util_1.validateTemplate)(content, schema);
+        if (unbalancedBlocks.length) {
+            throw new common_1.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 common_1.UnprocessableEntityException(`Variáveis obrigatórias ausentes do conteúdo: ${missingRequired.join(', ')}. ` +
+                'Envie allow_missing_variables=true para salvar mesmo assim.');
+        }
+        const warnings = [];
+        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.
+     */
+    missingPhraseWarnings(definition, content) {
+        const phrases = definition === null || definition === void 0 ? void 0 : definition.requiredPhrases;
+        if (!(phrases === null || phrases === void 0 ? void 0 : 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)`];
+    }
     async findById(id) {
-        const rows = await this.prisma.$queryRaw `
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+        const rows = await this.prisma.$queryRaw(api_prisma_1.Prisma.sql `
+      SELECT ${INSTRUCTION_COLUMNS}
       FROM ai_instruction WHERE id = ${id} LIMIT 1
-    `;
+    `);
+        return (rows === null || rows === void 0 ? void 0 : rows[0]) || null;
+    }
+    async findBySlug(slug) {
+        const rows = await this.prisma.$queryRaw(api_prisma_1.Prisma.sql `
+      SELECT ${INSTRUCTION_COLUMNS}
+      FROM ai_instruction WHERE slug = ${slug} LIMIT 1
+    `);
         return (rows === null || rows === void 0 ? void 0 : rows[0]) || null;
     }
     async findActiveBySlug(slug) {
-        const rows = await this.prisma.$queryRaw `
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+        const rows = await this.prisma.$queryRaw(api_prisma_1.Prisma.sql `
+      SELECT ${INSTRUCTION_COLUMNS}
       FROM ai_instruction WHERE slug = ${slug} AND is_active = TRUE LIMIT 1
-    `;
+    `);
         return (rows === null || rows === void 0 ? void 0 : rows[0]) || null;
     }
     async findActiveByLayer(layer, moduleSlug) {
         if (moduleSlug) {
-            const rows = await this.prisma.$queryRaw `
-        SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-               is_active, version, created_at, updated_at
+            const rows = await this.prisma.$queryRaw(api_prisma_1.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 === null || rows === void 0 ? void 0 : rows[0])
                 return rows[0];
         }
-        const rows = await this.prisma.$queryRaw `
-      SELECT id, slug, layer, name, content, variables_schema, locale, module_slug,
-             is_active, version, created_at, updated_at
+        const rows = await this.prisma.$queryRaw(api_prisma_1.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 === null || rows === void 0 ? void 0 : rows[0]) || null;
     }
     async saveVersion(instructionId, version, content, changeNote, createdById) {