@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/templates/code/dotnet/ai-agents/AgentBootstrap.cs.template

@@ -0,0 +1,39 @@
+// TEMPLATE: AgentBootstrap.cs
+// PURPOSE: Extension method to register ModelRegistry + a default agent in DI.
+// READS STANDARDS: ai-agents-setup, ai-agents-providers-model-registry
+// PLACEHOLDERS:
+//   {{PROJECT_NAMESPACE}}     — root namespace of the project
+//   {{DEFAULT_AGENT_NAME}}    — first agent name (e.g., "DefaultAssistant")
+//   {{DEFAULT_INSTRUCTIONS}}  — system prompt for default agent (1 line)
+// LAST-VERIFIED: 2026-05-19 (MAF 1.0 GA)
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public static class AgentBootstrap
+{
+    /// <summary>
+    /// Register ModelRegistry (singleton) and the default agent.
+    /// Additional agents register themselves via builder.AddAIAgent("Name", ...).
+    /// </summary>
+    public static WebApplicationBuilder AddMafAgents(this WebApplicationBuilder builder)
+    {
+        // Single source of truth for model selection
+        builder.Services.AddSingleton<ModelRegistry>();
+
+        // Default agent — uses the default alias from model-registry.json
+        builder.Services.AddKeyedSingleton<AIAgent>("{{DEFAULT_AGENT_NAME}}", (sp, _) =>
+        {
+            var registry = sp.GetRequiredService<ModelRegistry>();
+            var chatClient = registry.GetChatClient(registry.DefaultAlias);
+            return chatClient.AsAIAgent(
+                instructions: "{{DEFAULT_INSTRUCTIONS}}",
+                name: "{{DEFAULT_AGENT_NAME}}");
+        });
+
+        return builder;
+    }
+}

package/framework/templates/code/dotnet/ai-agents/EmbeddingService.cs.template

@@ -0,0 +1,68 @@
+// TEMPLATE: EmbeddingService.cs
+// PURPOSE: Generates embeddings for RAG indexing and query, via IEmbeddingGenerator.
+// READS STANDARD: ai-agents-rag-custom-pgvector
+// PLACEHOLDERS:
+//   {{PROJECT_NAMESPACE}}  — root namespace of the project (e.g., MyProject)
+// LAST-VERIFIED: 2026-05-19
+//
+// IMPORTANT — IEmbeddingGenerator registration (in Program.cs of the project):
+//   The project must register IEmbeddingGenerator<string, Embedding<float>> in DI.
+//   Example for OpenAI text-embedding-3-small (the canonical "embeddings" alias):
+//
+//   builder.Services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp =>
+//   {
+//       var cfg = sp.GetRequiredService<IConfiguration>();
+//       return new OpenAIClient(cfg["OpenAI:ApiKey"]!)
+//           .GetEmbeddingClient("text-embedding-3-small")
+//           .AsIEmbeddingGenerator();
+//   });
+//
+//   For other providers (Google, Anthropic, Ollama) adapt the client construction —
+//   see ai-agents-providers-model-registry §providers for verified SDKs.
+
+using Microsoft.Extensions.AI;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+/// <summary>
+/// Generates text embeddings for RAG indexing and query.
+/// Wraps <see cref="IEmbeddingGenerator{TInput,TEmbedding}"/> so the rest of the project
+/// does not take a direct dependency on the underlying provider SDK.
+/// </summary>
+public sealed class EmbeddingService(IEmbeddingGenerator<string, Embedding<float>> generator)
+{
+    /// <summary>
+    /// Generates an embedding vector for a single text (used at query time).
+    /// </summary>
+    /// <param name="text">The text to embed.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>The embedding vector as <see cref="ReadOnlyMemory{T}"/> of float.</returns>
+    public async Task<ReadOnlyMemory<float>> EmbedAsync(
+        string text,
+        CancellationToken ct = default)
+    {
+        // GenerateAsync is the verified API: returns GeneratedEmbeddings<Embedding<float>>.
+        // Each Embedding<float>.Vector is a ReadOnlyMemory<float>.
+        // Source: Microsoft Learn — microsoft-extensions-ai (verified 2026-05-19).
+        GeneratedEmbeddings<Embedding<float>> result =
+            await generator.GenerateAsync([text], cancellationToken: ct);
+
+        return result[0].Vector;
+    }
+
+    /// <summary>
+    /// Generates embedding vectors for a batch of texts (used during document indexing).
+    /// </summary>
+    /// <param name="texts">The texts to embed.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>Embedding vectors in the same order as the input texts.</returns>
+    public async Task<IReadOnlyList<ReadOnlyMemory<float>>> EmbedBatchAsync(
+        IReadOnlyList<string> texts,
+        CancellationToken ct = default)
+    {
+        GeneratedEmbeddings<Embedding<float>> result =
+            await generator.GenerateAsync(texts, cancellationToken: ct);
+
+        return [.. result.Select(e => e.Vector)];
+    }
+}

package/framework/templates/code/dotnet/ai-agents/ModelRegistry.cs.template

@@ -0,0 +1,117 @@
+// TEMPLATE: ModelRegistry.cs
+// PURPOSE: Reads config/model-registry.json at startup and exposes IChatClient by alias.
+// READS STANDARD: ai-agents-providers-model-registry
+// PROVIDERS: openai + ollama implemented below. To add google / anthropic / azure-openai,
+//            follow the same pattern — see ai-agents-providers-model-registry §providers
+//            (that standard is the source of truth for provider SDKs).
+// PLACEHOLDERS:
+//   {{PROJECT_NAMESPACE}}     — root namespace of the project (e.g., MyProject)
+//   {{REGISTRY_PATH}}         — path to model-registry.json relative to app base
+//                              (default: "config/model-registry.json")
+// LAST-VERIFIED: 2026-05-19 (MAF 1.0 GA, OpenAI SDK 2.x)
+
+using System.ClientModel;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Hosting;
+using OpenAI;
+using OpenAI.Chat;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+public sealed class ModelRegistry
+{
+    private readonly Dictionary<string, ModelAlias> _aliases;
+    private readonly Dictionary<string, IChatClient> _chatClientCache = new();
+    private readonly IConfiguration _config;
+    private readonly object _lock = new();
+
+    public ModelRegistry(IConfiguration config, IHostEnvironment env)
+    {
+        _config = config;
+        var path = Path.Combine(env.ContentRootPath, "{{REGISTRY_PATH}}");
+        if (!File.Exists(path))
+            throw new InvalidOperationException($"Model registry not found at {path}");
+
+        var json = File.ReadAllText(path);
+        var doc = JsonSerializer.Deserialize<RegistryDocument>(json, JsonOpts)
+            ?? throw new InvalidOperationException("Empty model-registry.json");
+        _aliases = doc.Aliases;
+        DefaultAlias = doc.DefaultAlias;
+    }
+
+    /// <summary>The alias used when a caller does not specify one (from model-registry.json).</summary>
+    public string DefaultAlias { get; }
+
+    public IChatClient GetChatClient(string alias)
+    {
+        if (!_aliases.TryGetValue(alias, out var spec))
+            throw new InvalidOperationException($"Unknown model alias: {alias}");
+
+        lock (_lock)
+        {
+            if (_chatClientCache.TryGetValue(alias, out var cached))
+                return cached;
+
+            var client = spec.Provider switch
+            {
+                "openai" => BuildOpenAI(spec),
+                "ollama" => BuildOllama(spec),
+                // To add a provider, implement Build<Provider>(spec) following the
+                // pattern below and add a case here. Confirm the NuGet SDK first —
+                // see ai-agents-providers-model-registry §providers.
+                //   "google"       => BuildGoogle(spec),
+                //   "anthropic"    => BuildAnthropic(spec),
+                //   "azure-openai" => BuildAzureOpenAI(spec),
+                _ => throw new NotSupportedException(
+                    $"Provider '{spec.Provider}' has no branch. Add it following " +
+                    $"the pattern in ai-agents-providers-model-registry.")
+            };
+
+            _chatClientCache[alias] = client;
+            return client;
+        }
+    }
+
+    private IChatClient BuildOpenAI(ModelAlias spec)
+    {
+        var apiKey = _config["OpenAI:ApiKey"]
+            ?? throw new InvalidOperationException("OpenAI:ApiKey not configured");
+        return new ChatClient(spec.Model, apiKey).AsIChatClient();
+    }
+
+    private IChatClient BuildOllama(ModelAlias spec)
+    {
+        // Ollama exposes an OpenAI-compatible endpoint — reuse the OpenAI ChatClient.
+        var endpoint = spec.Options?.GetValueOrDefault("endpoint")?.ToString()
+            ?? "http://localhost:11434/v1";
+        return new ChatClient(
+                spec.Model,
+                new ApiKeyCredential("ollama"),  // any non-empty string
+                new OpenAIClientOptions { Endpoint = new Uri(endpoint) })
+            .AsIChatClient();
+    }
+
+    private static readonly JsonSerializerOptions JsonOpts = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true
+    };
+
+    // NOTE: Fallback is parsed but not yet acted on. Implementing automatic
+    // provider failover (retry on rate-limit/outage) is reserved for a later wave.
+    private sealed record RegistryDocument(
+        string Version,
+        string DefaultAlias,
+        Dictionary<string, ModelAlias> Aliases,
+        Dictionary<string, string>? Fallback
+    );
+
+    public sealed record ModelAlias(
+        string Provider,
+        string Model,
+        Dictionary<string, object>? Options
+    );
+}

package/framework/templates/code/dotnet/ai-agents/PromptRepository.cs.template

@@ -0,0 +1,95 @@
+// TEMPLATE: PromptRepository.cs
+// PURPOSE: Loads agent system prompts from the agent_prompts table, with in-memory caching.
+// READS STANDARD: ai-agents-prompts-in-db
+// PLACEHOLDERS:
+//   {{PROJECT_NAMESPACE}}  — root namespace of the project
+// LAST-VERIFIED: 2026-05-19
+
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Caching.Memory;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+// ---------------------------------------------------------------------------
+// Entity — map this to the agent_prompts table (EF Core convention mapping).
+// Alternatively, configure via Fluent API in your DbContext.OnModelCreating.
+// ---------------------------------------------------------------------------
+
+/// <summary>
+/// EF Core entity for the agent_prompts table.
+/// Content is immutable once written — use INSERT + flip is_active for versioning.
+/// </summary>
+public sealed class AgentPrompt
+{
+    public Guid Id { get; init; } = Guid.CreateVersion7();
+    public required string AgentKey { get; init; }
+    public int Version { get; init; }
+    public required string Content { get; init; }
+    public bool IsActive { get; set; }
+    public DateTimeOffset CreatedAt { get; init; } = DateTimeOffset.UtcNow;
+}
+
+// ---------------------------------------------------------------------------
+// Interface
+// ---------------------------------------------------------------------------
+
+/// <summary>
+/// Provides the active system-prompt content for a named agent.
+/// </summary>
+public interface IPromptRepository
+{
+    /// <summary>
+    /// Returns the content of the currently active prompt for <paramref name="agentKey"/>.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when no row with <c>is_active = true</c> exists for <paramref name="agentKey"/>.
+    /// </exception>
+    Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+// NOTE: Register in Program.cs (or a bootstrap extension):
+//   builder.Services.AddMemoryCache();
+//   builder.Services.AddScoped<IPromptRepository, PromptRepository>();
+//
+// The DbContext must expose:  public DbSet<AgentPrompt> AgentPrompts { get; set; }
+// Replace YourDbContext below with the actual DbContext type of the project.
+
+/// <summary>
+/// Reads the active agent prompt from the database with an in-memory cache
+/// (default TTL: 5 minutes sliding). Cache invalidation is time-based;
+/// for immediate invalidation after a prompt update call
+/// <c>IMemoryCache.Remove($"agent_prompt:{agentKey}")</c>.
+/// </summary>
+public sealed class PromptRepository(YourDbContext db, IMemoryCache cache) : IPromptRepository
+{
+    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(5);
+
+    public async Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default)
+    {
+        var cacheKey = $"agent_prompt:{agentKey}";
+
+        if (cache.TryGetValue(cacheKey, out string? cached) && cached is not null)
+            return cached;
+
+        var content = await db.AgentPrompts
+            .Where(p => p.AgentKey == agentKey && p.IsActive)
+            .Select(p => p.Content)
+            .FirstOrDefaultAsync(ct);
+
+        if (content is null)
+            throw new InvalidOperationException(
+                $"No active prompt found for agent '{agentKey}'. " +
+                "Insert a row in agent_prompts with is_active = true for this agent_key.");
+
+        cache.Set(cacheKey, content, new MemoryCacheEntryOptions
+        {
+            SlidingExpiration = CacheTtl
+        });
+
+        return content;
+    }
+}

package/framework/templates/code/dotnet/ai-agents/ResilientToolMiddleware.cs.template

@@ -0,0 +1,61 @@
+// TEMPLATE: ResilientToolMiddleware.cs
+// PURPOSE: Function-calling middleware — retry/rate-limit resilience + anti-hallucination arg validation.
+// READS STANDARD: ai-agents-middleware-patterns
+// PLACEHOLDERS:
+//   {{PROJECT_NAMESPACE}}  — root namespace of the project
+// LAST-VERIFIED: 2026-05-19
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+/// <summary>
+/// Function-calling middleware that provides resilience (rate-limit + timeout handling)
+/// and anti-hallucination argument validation.
+///
+/// Registration:
+///   agent.AsBuilder().Use(ResilientToolMiddleware.Handle).Build();
+/// </summary>
+public static class ResilientToolMiddleware
+{
+    public static async ValueTask<object?> Handle(
+        AIAgent agent,
+        FunctionInvocationContext context,
+        Func<FunctionInvocationContext, CancellationToken, ValueTask<object?>> next,
+        CancellationToken cancellationToken)
+    {
+        // ─── Anti-hallucination: validate LLM-generated arguments BEFORE calling the tool ───
+        // If an argument is malformed, return a descriptive error string — the agent will
+        // self-correct on the next iteration without needing an external retry.
+        //
+        // Example: validate 'date' is ISO 8601
+        if (context.Arguments.TryGetValue("date", out var dateArg)
+            && !DateTime.TryParse(dateArg?.ToString(), out _))
+        {
+            return $"Invalid date format for '{context.Function.Name}'. Expected ISO 8601 (e.g. 2026-01-31).";
+        }
+        //
+        // Add additional argument validations here following the same pattern:
+        //   if (context.Arguments.TryGetValue("argName", out var val) && <invalid condition>)
+        //       return $"Descriptive error for '{context.Function.Name}': <what was wrong>.";
+
+        // ─── Resilience: execute tool and handle failures ───
+        try
+        {
+            return await next(context, cancellationToken);
+        }
+        catch (HttpRequestException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
+        {
+            return "Service is temporarily busy. Please try again in a moment.";
+        }
+        catch (TimeoutException)
+        {
+            return $"Tool '{context.Function.Name}' timed out. Try a simpler query.";
+        }
+        catch (Exception ex)
+        {
+            return $"Error in {context.Function.Name}: {ex.Message}";
+        }
+    }
+}

package/framework/templates/code/dotnet/ai-agents/VectorSearchTool.cs.template

@@ -0,0 +1,107 @@
+// TEMPLATE: VectorSearchTool.cs
+// PURPOSE: A typed MAF tool that retrieves relevant chunks from the pgvector knowledge base.
+// READS STANDARD: ai-agents-rag-custom-pgvector
+// PLACEHOLDERS:
+//   {{PROJECT_NAMESPACE}}  — root namespace of the project (e.g., MyProject)
+// LAST-VERIFIED: 2026-05-19
+//
+// SECURITY NOTE — tenant_id:
+//   tenant_id is resolved from the injected ITenantContext (or equivalent auth accessor),
+//   NEVER from a tool parameter visible to the LLM. A model-facing tenant parameter would
+//   allow prompt-injection to cross tenant boundaries.
+//
+// NPGSQL + PGVECTOR PARAMETER BINDING:
+//   This template uses NpgsqlDataSource (raw SQL) for the cosine-distance query.
+//   The project must call dataSourceBuilder.UseVector() before building the data source
+//   so Npgsql can map the vector type — see infrastructure-neon-pgvector.
+//
+//   // VERIFY: The exact Npgsql parameter binding for a pgvector type has been written
+//   // conservatively below using new Pgvector.Vector(float[]).
+//   // Confirmed pattern from neon-pgvector standard (Pgvector package):
+//   //   cmd.Parameters.AddWithValue("queryVec", new Pgvector.Vector(embedding.ToArray()));
+//   // If the project uses a different Npgsql/Pgvector version, verify the parameter API.
+//
+// REGISTRATION (in agent setup code):
+//   var tool = sp.GetRequiredService<VectorSearchTool>();
+//   var agent = modelRegistry.GetChatClient("text-default")
+//       .AsAIAgent(
+//           instructions: systemPrompt,
+//           tools: [AIFunctionFactory.Create(tool.SearchAsync)]);
+//
+// ALTERNATIVE — EF Core:
+//   If the project already wires pgvector through EF Core (UseVector(), HasMethod("hnsw")),
+//   replace the NpgsqlDataSource usage with db.Database.SqlQuery<string>() per
+//   infrastructure-neon-pgvector. The tool method signature stays identical.
+
+using System.ComponentModel;
+using Npgsql;
+using Pgvector;
+
+namespace {{PROJECT_NAMESPACE}}.AI;
+
+/// <summary>
+/// MAF tool: searches the knowledge base for chunks semantically similar to a query.
+/// Registered on an agent via <c>AIFunctionFactory.Create(tool.SearchAsync)</c>.
+/// The agent calls this autonomously when it needs grounding context.
+/// </summary>
+public sealed class VectorSearchTool(
+    EmbeddingService embeddingService,
+    NpgsqlDataSource dataSource,
+    ITenantContext tenantContext)   // Resolved from DI — scoped to the authenticated request.
+                                    // Replace with Guid currentTenantId if a simpler accessor is preferred.
+{
+    private const int DefaultTopK = 5;
+
+    /// <summary>
+    /// Searches the knowledge base for context relevant to a question.
+    /// </summary>
+    /// <param name="query">The natural-language search query.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>
+    /// Concatenated text of the top matching chunks, separated by double newlines.
+    /// Returns an empty string if no results are found.
+    /// </returns>
+    [Description("Searches the knowledge base for context relevant to a question")]
+    public async Task<string> SearchAsync(
+        [Description("the natural-language search query")] string query,
+        CancellationToken ct = default)
+    {
+        // 1. Embed the query at search time.
+        ReadOnlyMemory<float> queryVector = await embeddingService.EmbedAsync(query, ct);
+
+        // 2. Resolve tenant from auth context — never from a model-supplied parameter.
+        Guid tenantId = tenantContext.CurrentTenantId;
+
+        // 3. Run parameterized cosine-distance query.
+        //    ORDER BY embedding <=> @queryVec sorts ascending by distance (most similar first).
+        const string sql = """
+            SELECT content
+            FROM   kb_embeddings
+            WHERE  tenant_id = @tenant
+            ORDER  BY embedding <=> @queryVec
+            LIMIT  @topK
+            """;
+
+        var chunks = new List<string>(DefaultTopK);
+
+        await using var conn = await dataSource.OpenConnectionAsync(ct);
+        await using var cmd = new NpgsqlCommand(sql, conn);
+
+        cmd.Parameters.AddWithValue("tenant", tenantId);
+
+        // VERIFY: Pgvector.Vector wraps a float[] for Npgsql parameter binding.
+        // The project must have called dataSourceBuilder.UseVector() on NpgsqlDataSourceBuilder.
+        // NuGet: Pgvector (matches the Pgvector.EntityFrameworkCore used in neon-pgvector.md).
+        cmd.Parameters.AddWithValue("queryVec", new Vector(queryVector.ToArray()));
+
+        cmd.Parameters.AddWithValue("topK", DefaultTopK);
+
+        await using var reader = await cmd.ExecuteReaderAsync(ct);
+        while (await reader.ReadAsync(ct))
+        {
+            chunks.Add(reader.GetString(0));
+        }
+
+        return string.Join("\n\n", chunks);
+    }
+}

package/framework/templates/code/dotnet/ai-agents/model-registry.json.template

@@ -0,0 +1,58 @@
+// TEMPLATE: model-registry.json (place in project at config/model-registry.json)
+// PURPOSE: Single source of truth for model selection. Agents reference aliases, not models.
+// READS STANDARD: ai-agents-providers-model-registry
+// PROVIDERS: openai + ollama work out-of-the-box with the ModelRegistry template.
+//            For google / anthropic, add a provider branch first (see the standard).
+// PLACEHOLDERS:
+//   {{PROJECT_DEFAULT_ALIAS}} — alias used when none specified (default: "text-default")
+// LAST-VERIFIED: 2026-05-19
+{
+  "$schema": "./model-registry.schema.json",
+  "version": "1.0",
+  "defaultAlias": "{{PROJECT_DEFAULT_ALIAS}}",
+  "aliases": {
+    "text-default": {
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "options": { "temperature": 0.7 }
+    },
+    "text-heavy": {
+      "provider": "openai",
+      "model": "gpt-4o",
+      "options": { "temperature": 0.5 }
+    },
+    "reasoning": {
+      "provider": "openai",
+      "model": "o3-mini",
+      "options": { "reasoningEffort": "medium" }
+    },
+    "long-form": {
+      "provider": "anthropic",
+      "model": "claude-sonnet-4-6",
+      "options": {}
+    },
+    "vision": {
+      "provider": "google",
+      "model": "gemini-2.5-flash",
+      "options": {}
+    },
+    "embeddings": {
+      "provider": "openai",
+      "model": "text-embedding-3-small",
+      "options": { "dimensions": 1536 }
+    },
+    "local-dev": {
+      "provider": "ollama",
+      "model": "llama3.2:3b",
+      "options": { "endpoint": "http://localhost:11434/v1" }
+    },
+    "transcription": {
+      "provider": "openai",
+      "model": "whisper-1",
+      "options": {}
+    }
+  },
+  "fallback": {
+    "text-default": "ollama/llama3.2:3b"
+  }
+}

package/framework/templates/code/sql/ai-agents/agent-prompts-migration.sql.template

@@ -0,0 +1,58 @@
+-- TEMPLATE: agent-prompts-migration.sql
+-- PURPOSE: Creates the agent_prompts table for runtime-editable, versioned agent instructions.
+-- READS STANDARD: ai-agents-prompts-in-db
+-- PLACEHOLDERS:
+--   {{SCHEMA}}  — target schema (default: public)
+-- LAST-VERIFIED: 2026-05-19
+
+-- ============================================================
+-- 1. TABLE
+-- ============================================================
+
+CREATE TABLE {{SCHEMA}}.agent_prompts (
+    id          uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+    agent_key   text        NOT NULL,
+    version     int         NOT NULL,
+    content     text        NOT NULL,
+    is_active   boolean     NOT NULL DEFAULT false,
+    created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE  {{SCHEMA}}.agent_prompts              IS 'Runtime-editable, versioned system prompts for AI agents.';
+COMMENT ON COLUMN {{SCHEMA}}.agent_prompts.agent_key    IS 'Logical identifier for the agent (e.g. ''proposal-agent'').';
+COMMENT ON COLUMN {{SCHEMA}}.agent_prompts.version      IS 'Monotonically increasing per agent_key. Never reuse a version number.';
+COMMENT ON COLUMN {{SCHEMA}}.agent_prompts.content      IS 'Immutable system-prompt text. UPDATE of this column is forbidden — insert a new row instead.';
+COMMENT ON COLUMN {{SCHEMA}}.agent_prompts.is_active    IS 'Exactly one row per agent_key may have is_active = true (enforced by ix_agent_prompts_active).';
+COMMENT ON COLUMN {{SCHEMA}}.agent_prompts.created_at   IS 'Audit timestamp. Set at insert time, never updated.';
+
+-- ============================================================
+-- 2. INDEXES
+-- ============================================================
+
+-- Unique partial index: enforces at DB level that only one active prompt
+-- exists per agent_key. Any attempt to INSERT a second active row for the
+-- same key will fail with a unique-constraint violation.
+CREATE UNIQUE INDEX ix_agent_prompts_active
+    ON {{SCHEMA}}.agent_prompts (agent_key)
+    WHERE is_active;
+
+-- Regular index for the PromptRepository lookup (agent_key + is_active filter).
+CREATE INDEX ix_agent_prompts_agent_key
+    ON {{SCHEMA}}.agent_prompts (agent_key);
+
+-- Unique index: prevents duplicate version numbers per agent_key.
+CREATE UNIQUE INDEX ix_agent_prompts_agent_key_version
+    ON {{SCHEMA}}.agent_prompts (agent_key, version);
+
+-- ============================================================
+-- 3. SEED (optional — remove if managed via backoffice)
+-- ============================================================
+
+-- INSERT INTO {{SCHEMA}}.agent_prompts (agent_key, version, content, is_active)
+-- VALUES ('my-agent', 1, 'You are a helpful assistant.', true);
+
+-- ============================================================
+-- ROLLBACK
+-- ============================================================
+
+-- DROP TABLE IF EXISTS {{SCHEMA}}.agent_prompts CASCADE;