@polymorphism-tech/morph-spec 7.7.3 → 7.8.1

package/framework/templates/code/dotnet/test.cs

@@ -6,9 +6,10 @@
 using FluentAssertions;
 using FluentValidation;
 using FluentValidation.Results;
-using Microsoft.Extensions.Logging;
-using NSubstitute;
-using {{pascalCase PROJECT_NAME}}.Repository;
+using Microsoft.Data.Sqlite;
+using Microsoft.EntityFrameworkCore;
+using {{pascalCase PROJECT_NAME}}.Database;
+using {{pascalCase PROJECT_NAME}}.Entities;
 using Xunit;
 
 namespace {{pascalCase PROJECT_NAME}}.Tests.Unit.Features.{{pascalCase FEATURE_NAME}};
@@ -19,19 +20,31 @@ namespace {{pascalCase PROJECT_NAME}}.Tests.Unit.Features.{{pascalCase FEATURE_N
 
 /// <summary>
 /// Unit tests for {{pascalCase FEATURE_NAME}} handlers.
-/// Tests handlers directly with mocked IRepository and IUnitOfWork.
+/// Tests handlers directly against a real ApplicationDbContext backed by
+/// in-memory SQLite (no mocks — DbSet is the repository, DbContext is the unit of work).
 /// </summary>
-public class {{pascalCase FEATURE_NAME}}HandlerTests
+public class {{pascalCase FEATURE_NAME}}HandlerTests : IDisposable
 {
-    private readonly IRepository<{{pascalCase FEATURE_NAME}}> _repository;
-    private readonly IUnitOfWork _unitOfWork;
-    private readonly ILogger<Create{{pascalCase FEATURE_NAME}}.Handler> _logger;
+    private readonly SqliteConnection _connection;
+    private readonly ApplicationDbContext _db;
 
     public {{pascalCase FEATURE_NAME}}HandlerTests()
     {
-        _repository = Substitute.For<IRepository<{{pascalCase FEATURE_NAME}}>>();
-        _unitOfWork = Substitute.For<IUnitOfWork>();
-        _logger = Substitute.For<ILogger<Create{{pascalCase FEATURE_NAME}}.Handler>>();
+        _connection = new SqliteConnection("DataSource=:memory:");
+        _connection.Open();
+
+        var options = new DbContextOptionsBuilder<ApplicationDbContext>()
+            .UseSqlite(_connection)
+            .Options;
+
+        _db = new ApplicationDbContext(options);
+        _db.Database.EnsureCreated();
+    }
+
+    public void Dispose()
+    {
+        _db.Dispose();
+        _connection.Dispose();
     }
 
     #region Create Handler Tests
@@ -40,14 +53,8 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
     public async Task Create_HandleAsync_WithValidCommand_ReturnsSuccessResult()
     {
         // Arrange
-        var command = new Create{{pascalCase FEATURE_NAME}}.Command("Test {{pascalCase FEATURE_NAME}}");
-        var handler = new Create{{pascalCase FEATURE_NAME}}.Handler(_repository, _unitOfWork, _logger);
-
-        _repository.AddAsync(Arg.Any<{{pascalCase FEATURE_NAME}}>(), Arg.Any<CancellationToken>())
-            .Returns(callInfo => callInfo.Arg<{{pascalCase FEATURE_NAME}}>());
-
-        _unitOfWork.CommitAsync(Arg.Any<CancellationToken>())
-            .Returns(1);
+        var command = new Create{{pascalCase FEATURE_NAME}}Request("Test {{pascalCase FEATURE_NAME}}");
+        var handler = new Create{{pascalCase FEATURE_NAME}}Handler(_db);
 
         // Act
         var result = await handler.HandleAsync(command, CancellationToken.None);
@@ -55,31 +62,9 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
         // Assert
         result.IsSuccess.Should().BeTrue();
         result.Value.Should().NotBeNull();
-        result.Value.Name.Should().Be("Test {{pascalCase FEATURE_NAME}}");
 
-        await _repository.Received(1).AddAsync(Arg.Any<{{pascalCase FEATURE_NAME}}>(), Arg.Any<CancellationToken>());
-        await _unitOfWork.Received(1).CommitAsync(Arg.Any<CancellationToken>());
-    }
-
-    [Fact]
-    public async Task Create_HandleAsync_WhenCommitFails_ReturnsFailureResult()
-    {
-        // Arrange
-        var command = new Create{{pascalCase FEATURE_NAME}}.Command("Test {{pascalCase FEATURE_NAME}}");
-        var handler = new Create{{pascalCase FEATURE_NAME}}.Handler(_repository, _unitOfWork, _logger);
-
-        _repository.AddAsync(Arg.Any<{{pascalCase FEATURE_NAME}}>(), Arg.Any<CancellationToken>())
-            .Returns(callInfo => callInfo.Arg<{{pascalCase FEATURE_NAME}}>());
-
-        _unitOfWork.CommitAsync(Arg.Any<CancellationToken>())
-            .ThrowsAsync(new InvalidOperationException("Database error"));
-
-        // Act
-        var act = async () => await handler.HandleAsync(command, CancellationToken.None);
-
-        // Assert
-        await act.Should().ThrowAsync<InvalidOperationException>()
-            .WithMessage("Database error");
+        var persisted = await _db.Set<{{pascalCase FEATURE_NAME}}>().SingleAsync();
+        persisted.Name.Should().Be("Test {{pascalCase FEATURE_NAME}}");
     }
 
     #endregion
@@ -90,12 +75,12 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
     public async Task GetById_HandleAsync_WithValidId_ReturnsSuccessResult()
     {
         // Arrange
-        var query = new GetById{{pascalCase FEATURE_NAME}}.Query(1);
-        var entity = CreateTestEntity(1, "Test {{pascalCase FEATURE_NAME}}");
-        var handler = new GetById{{pascalCase FEATURE_NAME}}.Handler(_repository);
+        var entity = CreateTestEntity("Test {{pascalCase FEATURE_NAME}}");
+        _db.Set<{{pascalCase FEATURE_NAME}}>().Add(entity);
+        await _db.SaveChangesAsync();
 
-        _repository.GetByIdAsync(1, Arg.Any<CancellationToken>())
-            .Returns(entity);
+        var query = new Get{{pascalCase FEATURE_NAME}}ByIdRequest(entity.Id);
+        var handler = new Get{{pascalCase FEATURE_NAME}}ByIdHandler(_db);
 
         // Act
         var result = await handler.HandleAsync(query, CancellationToken.None);
@@ -110,11 +95,8 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
     public async Task GetById_HandleAsync_WithInvalidId_ReturnsFailureResult()
     {
         // Arrange
-        var query = new GetById{{pascalCase FEATURE_NAME}}.Query(999);
-        var handler = new GetById{{pascalCase FEATURE_NAME}}.Handler(_repository);
-
-        _repository.GetByIdAsync(999, Arg.Any<CancellationToken>())
-            .Returns(({{pascalCase FEATURE_NAME}}?)null);
+        var query = new Get{{pascalCase FEATURE_NAME}}ByIdRequest(Guid.CreateVersion7());
+        var handler = new Get{{pascalCase FEATURE_NAME}}ByIdHandler(_db);
 
         // Act
         var result = await handler.HandleAsync(query, CancellationToken.None);
@@ -131,15 +113,12 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
     public async Task Update_HandleAsync_WithValidCommand_ReturnsSuccessResult()
     {
         // Arrange
-        var command = new Update{{pascalCase FEATURE_NAME}}.Command(1, "Updated Name");
-        var entity = CreateTestEntity(1, "Original Name");
-        var handler = new Update{{pascalCase FEATURE_NAME}}.Handler(_repository, _unitOfWork);
-
-        _repository.GetByIdAsync(1, Arg.Any<CancellationToken>())
-            .Returns(entity);
+        var entity = CreateTestEntity("Original Name");
+        _db.Set<{{pascalCase FEATURE_NAME}}>().Add(entity);
+        await _db.SaveChangesAsync();
 
-        _unitOfWork.CommitAsync(Arg.Any<CancellationToken>())
-            .Returns(1);
+        var command = new Update{{pascalCase FEATURE_NAME}}Request(entity.Id, "Updated Name");
+        var handler = new Update{{pascalCase FEATURE_NAME}}Handler(_db);
 
         // Act
         var result = await handler.HandleAsync(command, CancellationToken.None);
@@ -147,26 +126,22 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
         // Assert
         result.IsSuccess.Should().BeTrue();
 
-        await _repository.Received(1).UpdateAsync(Arg.Any<{{pascalCase FEATURE_NAME}}>(), Arg.Any<CancellationToken>());
-        await _unitOfWork.Received(1).CommitAsync(Arg.Any<CancellationToken>());
+        var persisted = await _db.Set<{{pascalCase FEATURE_NAME}}>().SingleAsync(x => x.Id == entity.Id);
+        persisted.Name.Should().Be("Updated Name");
     }
 
     [Fact]
     public async Task Update_HandleAsync_WithNonExistentId_ReturnsFailureResult()
     {
         // Arrange
-        var command = new Update{{pascalCase FEATURE_NAME}}.Command(999, "Updated");
-        var handler = new Update{{pascalCase FEATURE_NAME}}.Handler(_repository, _unitOfWork);
-
-        _repository.GetByIdAsync(999, Arg.Any<CancellationToken>())
-            .Returns(({{pascalCase FEATURE_NAME}}?)null);
+        var command = new Update{{pascalCase FEATURE_NAME}}Request(Guid.CreateVersion7(), "Updated");
+        var handler = new Update{{pascalCase FEATURE_NAME}}Handler(_db);
 
         // Act
         var result = await handler.HandleAsync(command, CancellationToken.None);
 
         // Assert
         result.IsSuccess.Should().BeFalse();
-        await _unitOfWork.DidNotReceive().CommitAsync(Arg.Any<CancellationToken>());
     }
 
     #endregion
@@ -177,15 +152,12 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
     public async Task Delete_HandleAsync_WithValidId_ReturnsSuccessResult()
     {
         // Arrange
-        var command = new Delete{{pascalCase FEATURE_NAME}}.Command(1);
-        var entity = CreateTestEntity(1, "To Delete");
-        var handler = new Delete{{pascalCase FEATURE_NAME}}.Handler(_repository, _unitOfWork);
+        var entity = CreateTestEntity("To Delete");
+        _db.Set<{{pascalCase FEATURE_NAME}}>().Add(entity);
+        await _db.SaveChangesAsync();
 
-        _repository.GetByIdAsync(1, Arg.Any<CancellationToken>())
-            .Returns(entity);
-
-        _unitOfWork.CommitAsync(Arg.Any<CancellationToken>())
-            .Returns(1);
+        var command = new Delete{{pascalCase FEATURE_NAME}}Request(entity.Id);
+        var handler = new Delete{{pascalCase FEATURE_NAME}}Handler(_db);
 
         // Act
         var result = await handler.HandleAsync(command, CancellationToken.None);
@@ -193,36 +165,35 @@ public class {{pascalCase FEATURE_NAME}}HandlerTests
         // Assert
         result.IsSuccess.Should().BeTrue();
 
-        await _repository.Received(1).DeleteAsync(entity, Arg.Any<CancellationToken>());
-        await _unitOfWork.Received(1).CommitAsync(Arg.Any<CancellationToken>());
+        (await _db.Set<{{pascalCase FEATURE_NAME}}>().AnyAsync(x => x.Id == entity.Id)).Should().BeFalse();
     }
 
     [Fact]
     public async Task Delete_HandleAsync_WithNonExistentId_ReturnsFailureResult()
     {
         // Arrange
-        var command = new Delete{{pascalCase FEATURE_NAME}}.Command(999);
-        var handler = new Delete{{pascalCase FEATURE_NAME}}.Handler(_repository, _unitOfWork);
-
-        _repository.GetByIdAsync(999, Arg.Any<CancellationToken>())
-            .Returns(({{pascalCase FEATURE_NAME}}?)null);
+        var command = new Delete{{pascalCase FEATURE_NAME}}Request(Guid.CreateVersion7());
+        var handler = new Delete{{pascalCase FEATURE_NAME}}Handler(_db);
 
         // Act
         var result = await handler.HandleAsync(command, CancellationToken.None);
 
         // Assert
         result.IsSuccess.Should().BeFalse();
-        await _unitOfWork.DidNotReceive().CommitAsync(Arg.Any<CancellationToken>());
     }
 
     #endregion
 
     #region Helper Methods
 
-    private static {{pascalCase FEATURE_NAME}} CreateTestEntity(int id, string name)
+    private static {{pascalCase FEATURE_NAME}} CreateTestEntity(string name)
     {
-        return {{pascalCase FEATURE_NAME}}.Create(name);
-        // Note: In real tests, use reflection or a test factory to set the Id
+        return new {{pascalCase FEATURE_NAME}}
+        {
+            Id = Guid.CreateVersion7(),
+            Name = name,
+            // TODO: preencher demais campos obrigatórios da entidade
+        };
     }
 
     #endregion
@@ -244,8 +215,8 @@ public class {{pascalCase FEATURE_NAME}}ValidatorTests
     public async Task CreateValidator_WithValidCommand_PassesValidation()
     {
         // Arrange
-        var validator = new Create{{pascalCase FEATURE_NAME}}.Validator();
-        var command = new Create{{pascalCase FEATURE_NAME}}.Command("Valid Name");
+        var validator = new Create{{pascalCase FEATURE_NAME}}Validator();
+        var command = new Create{{pascalCase FEATURE_NAME}}Request("Valid Name");
 
         // Act
         ValidationResult result = await validator.ValidateAsync(command);
@@ -262,30 +233,30 @@ public class {{pascalCase FEATURE_NAME}}ValidatorTests
     public async Task CreateValidator_WithInvalidName_FailsValidation(string? name)
     {
         // Arrange
-        var validator = new Create{{pascalCase FEATURE_NAME}}.Validator();
-        var command = new Create{{pascalCase FEATURE_NAME}}.Command(name!);
+        var validator = new Create{{pascalCase FEATURE_NAME}}Validator();
+        var command = new Create{{pascalCase FEATURE_NAME}}Request(name!);
 
         // Act
         ValidationResult result = await validator.ValidateAsync(command);
 
         // Assert
         result.IsValid.Should().BeFalse();
-        result.Errors.Should().Contain(e => e.PropertyName == nameof(Create{{pascalCase FEATURE_NAME}}.Command.Name));
+        result.Errors.Should().Contain(e => e.PropertyName == nameof(Create{{pascalCase FEATURE_NAME}}Request.Name));
     }
 
     [Fact]
     public async Task CreateValidator_WithNameExceedingMaxLength_FailsValidation()
     {
         // Arrange
-        var validator = new Create{{pascalCase FEATURE_NAME}}.Validator();
-        var command = new Create{{pascalCase FEATURE_NAME}}.Command(new string('A', 201));
+        var validator = new Create{{pascalCase FEATURE_NAME}}Validator();
+        var command = new Create{{pascalCase FEATURE_NAME}}Request(new string('A', 201));
 
         // Act
         ValidationResult result = await validator.ValidateAsync(command);
 
         // Assert
         result.IsValid.Should().BeFalse();
-        result.Errors.Should().Contain(e => e.PropertyName == nameof(Create{{pascalCase FEATURE_NAME}}.Command.Name));
+        result.Errors.Should().Contain(e => e.PropertyName == nameof(Create{{pascalCase FEATURE_NAME}}Request.Name));
     }
 
     #endregion
@@ -296,8 +267,8 @@ public class {{pascalCase FEATURE_NAME}}ValidatorTests
     public async Task UpdateValidator_WithValidCommand_PassesValidation()
     {
         // Arrange
-        var validator = new Update{{pascalCase FEATURE_NAME}}.Validator();
-        var command = new Update{{pascalCase FEATURE_NAME}}.Command(1, "Updated Name");
+        var validator = new Update{{pascalCase FEATURE_NAME}}Validator();
+        var command = new Update{{pascalCase FEATURE_NAME}}Request(Guid.CreateVersion7(), "Updated Name");
 
         // Act
         ValidationResult result = await validator.ValidateAsync(command);
@@ -310,15 +281,15 @@ public class {{pascalCase FEATURE_NAME}}ValidatorTests
     public async Task UpdateValidator_WithInvalidId_FailsValidation()
     {
         // Arrange
-        var validator = new Update{{pascalCase FEATURE_NAME}}.Validator();
-        var command = new Update{{pascalCase FEATURE_NAME}}.Command(0, "Updated Name");
+        var validator = new Update{{pascalCase FEATURE_NAME}}Validator();
+        var command = new Update{{pascalCase FEATURE_NAME}}Request(Guid.Empty, "Updated Name");
 
         // Act
         ValidationResult result = await validator.ValidateAsync(command);
 
         // Assert
         result.IsValid.Should().BeFalse();
-        result.Errors.Should().Contain(e => e.PropertyName == nameof(Update{{pascalCase FEATURE_NAME}}.Command.Id));
+        result.Errors.Should().Contain(e => e.PropertyName == nameof(Update{{pascalCase FEATURE_NAME}}Request.Id));
     }
 
     #endregion

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

@@ -1,58 +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;
+-- 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;

package/framework/templates/code/sql/ai-agents/pgvector-embeddings-migration.sql.template

@@ -1,91 +1,91 @@
--- TEMPLATE: pgvector-embeddings-migration.sql
--- PURPOSE: Creates the kb_embeddings table for custom RAG — chunk storage with pgvector.
--- READS STANDARD: ai-agents-rag-custom-pgvector
--- PLACEHOLDERS:
---   {{SCHEMA}}  — target schema (default: public)
--- LAST-VERIFIED: 2026-05-19
---
--- PREREQUISITES:
---   - pgvector extension enabled in Neon (see infrastructure-neon-pgvector).
---   - NpgsqlDataSourceBuilder.UseVector() called in the project's DB setup.
---
--- DIMENSION NOTE:
---   embedding vector(1536) matches text-embedding-3-small (default 1536 dimensions).
---   If the project uses a different embedding model, adjust the dimension to match.
---   NEVER mix embedding models on a single column — vectors live in different spaces.
-
--- ============================================================
--- 1. EXTENSION
--- ============================================================
-
-CREATE EXTENSION IF NOT EXISTS vector;
-
--- ============================================================
--- 2. TABLE
--- ============================================================
-
-CREATE TABLE {{SCHEMA}}.kb_embeddings (
-    id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
-    tenant_id   uuid         NOT NULL,
-    source      text         NOT NULL,   -- document identifier or source URL
-    chunk_index int          NOT NULL,   -- position of this chunk within the source document
-    content     text         NOT NULL,   -- chunk text returned to the agent as context
-    embedding   vector(1536) NOT NULL,   -- vector dimension must match embedding model
-    metadata    jsonb        NOT NULL DEFAULT '{}',
-    created_at  timestamptz  NOT NULL DEFAULT now()
-);
-
-COMMENT ON TABLE  {{SCHEMA}}.kb_embeddings               IS 'RAG knowledge base — chunk text and pgvector embeddings for semantic search.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.tenant_id     IS 'Tenant partition. Every query MUST filter on this column. Never query across tenants.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.source        IS 'Document identifier or URL. Used for citation and re-indexing detection.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.chunk_index   IS 'Zero-based position of this chunk within the source document.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.content       IS 'Chunk text returned to the agent. Plain text, no markup.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.embedding     IS 'Float vector. Dimension MUST match the embedding model declared in model-registry.json.';
-COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.metadata      IS 'Arbitrary JSON metadata (section headers, page numbers, doc type, etc.). Used for filtering.';
-
--- ============================================================
--- 3. INDEXES
--- ============================================================
-
--- HNSW index for cosine similarity — production-grade recall, no training data required.
--- vector_cosine_ops: use <=> operator (cosine distance, ascending = most similar first).
--- m=16, ef_construction=64 are pgvector defaults. Tune per infrastructure-neon-pgvector §HNSW Parameters.
-CREATE INDEX ix_kb_embeddings_hnsw
-    ON {{SCHEMA}}.kb_embeddings
-    USING hnsw (embedding vector_cosine_ops)
-    WITH (m = 16, ef_construction = 64);
-
--- Index for the mandatory tenant_id filter (applied in every search query).
-CREATE INDEX ix_kb_embeddings_tenant
-    ON {{SCHEMA}}.kb_embeddings (tenant_id);
-
--- Composite index for source-level operations (re-indexing, deletion by document).
-CREATE INDEX ix_kb_embeddings_source
-    ON {{SCHEMA}}.kb_embeddings (tenant_id, source);
-
--- ============================================================
--- 4. ROW-LEVEL SECURITY (multi-tenant)
--- ============================================================
-
--- RLS enforces tenant isolation at the database level as a second line of defence.
--- The application already filters on tenant_id in every query; RLS is the backstop.
---
--- See templates/code/sql/postgresql-rls-policy.sql for the policy pattern that
--- binds app.current_tenant_id (a session-level setting) to the RLS policy.
---
--- Uncomment and adapt once RLS is wired in the project:
---
--- ALTER TABLE {{SCHEMA}}.kb_embeddings ENABLE ROW LEVEL SECURITY;
---
--- CREATE POLICY kb_embeddings_tenant_isolation
---     ON {{SCHEMA}}.kb_embeddings
---     USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
-
--- ============================================================
--- ROLLBACK
--- ============================================================
-
--- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_hnsw;
--- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_tenant;
--- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_source;
--- DROP TABLE IF EXISTS {{SCHEMA}}.kb_embeddings CASCADE;
+-- TEMPLATE: pgvector-embeddings-migration.sql
+-- PURPOSE: Creates the kb_embeddings table for custom RAG — chunk storage with pgvector.
+-- READS STANDARD: ai-agents-rag-custom-pgvector
+-- PLACEHOLDERS:
+--   {{SCHEMA}}  — target schema (default: public)
+-- LAST-VERIFIED: 2026-05-19
+--
+-- PREREQUISITES:
+--   - pgvector extension enabled in Neon (see infrastructure-neon-pgvector).
+--   - NpgsqlDataSourceBuilder.UseVector() called in the project's DB setup.
+--
+-- DIMENSION NOTE:
+--   embedding vector(1536) matches text-embedding-3-small (default 1536 dimensions).
+--   If the project uses a different embedding model, adjust the dimension to match.
+--   NEVER mix embedding models on a single column — vectors live in different spaces.
+
+-- ============================================================
+-- 1. EXTENSION
+-- ============================================================
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- ============================================================
+-- 2. TABLE
+-- ============================================================
+
+CREATE TABLE {{SCHEMA}}.kb_embeddings (
+    id          uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id   uuid         NOT NULL,
+    source      text         NOT NULL,   -- document identifier or source URL
+    chunk_index int          NOT NULL,   -- position of this chunk within the source document
+    content     text         NOT NULL,   -- chunk text returned to the agent as context
+    embedding   vector(1536) NOT NULL,   -- vector dimension must match embedding model
+    metadata    jsonb        NOT NULL DEFAULT '{}',
+    created_at  timestamptz  NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE  {{SCHEMA}}.kb_embeddings               IS 'RAG knowledge base — chunk text and pgvector embeddings for semantic search.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.tenant_id     IS 'Tenant partition. Every query MUST filter on this column. Never query across tenants.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.source        IS 'Document identifier or URL. Used for citation and re-indexing detection.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.chunk_index   IS 'Zero-based position of this chunk within the source document.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.content       IS 'Chunk text returned to the agent. Plain text, no markup.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.embedding     IS 'Float vector. Dimension MUST match the embedding model declared in model-registry.json.';
+COMMENT ON COLUMN {{SCHEMA}}.kb_embeddings.metadata      IS 'Arbitrary JSON metadata (section headers, page numbers, doc type, etc.). Used for filtering.';
+
+-- ============================================================
+-- 3. INDEXES
+-- ============================================================
+
+-- HNSW index for cosine similarity — production-grade recall, no training data required.
+-- vector_cosine_ops: use <=> operator (cosine distance, ascending = most similar first).
+-- m=16, ef_construction=64 are pgvector defaults. Tune per infrastructure-neon-pgvector §HNSW Parameters.
+CREATE INDEX ix_kb_embeddings_hnsw
+    ON {{SCHEMA}}.kb_embeddings
+    USING hnsw (embedding vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+
+-- Index for the mandatory tenant_id filter (applied in every search query).
+CREATE INDEX ix_kb_embeddings_tenant
+    ON {{SCHEMA}}.kb_embeddings (tenant_id);
+
+-- Composite index for source-level operations (re-indexing, deletion by document).
+CREATE INDEX ix_kb_embeddings_source
+    ON {{SCHEMA}}.kb_embeddings (tenant_id, source);
+
+-- ============================================================
+-- 4. ROW-LEVEL SECURITY (multi-tenant)
+-- ============================================================
+
+-- RLS enforces tenant isolation at the database level as a second line of defence.
+-- The application already filters on tenant_id in every query; RLS is the backstop.
+--
+-- See templates/code/sql/postgresql-rls-policy.sql for the policy pattern that
+-- binds app.current_tenant_id (a session-level setting) to the RLS policy.
+--
+-- Uncomment and adapt once RLS is wired in the project:
+--
+-- ALTER TABLE {{SCHEMA}}.kb_embeddings ENABLE ROW LEVEL SECURITY;
+--
+-- CREATE POLICY kb_embeddings_tenant_isolation
+--     ON {{SCHEMA}}.kb_embeddings
+--     USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
+
+-- ============================================================
+-- ROLLBACK
+-- ============================================================
+
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_hnsw;
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_tenant;
+-- DROP INDEX IF EXISTS {{SCHEMA}}.ix_kb_embeddings_source;
+-- DROP TABLE IF EXISTS {{SCHEMA}}.kb_embeddings CASCADE;