@polymorphism-tech/morph-spec 7.9.3 → 8.0.0

package/framework/templates/code/dotnet/database/migration.cs

@@ -1,83 +1,83 @@
-// ============================================================
-// EF CORE MIGRATION TEMPLATE
-// Generated by MORPH Framework
-// ============================================================
-
-using Microsoft.EntityFrameworkCore.Migrations;
-
-#nullable disable
-
-namespace {{NAMESPACE}}.Infrastructure.Data.Migrations;
-
-/// <inheritdoc />
-public partial class Add{{pascalCase FEATURE_NAME}} : Migration
-{
-    /// <inheritdoc />
-    protected override void Up(MigrationBuilder migrationBuilder)
-    {
-        migrationBuilder.CreateTable(
-            name: "{{pascalCase FEATURE_NAME}}s",
-            columns: table => new
-            {
-                Id = table.Column<int>(type: "int", nullable: false)
-                    .Annotation("SqlServer:Identity", "1, 1"),
-                Name = table.Column<string>(type: "nvarchar(200)", maxLength: 200, nullable: false),
-                Status = table.Column<string>(type: "nvarchar(50)", maxLength: 50, nullable: false),
-                CreatedAt = table.Column<DateTime>(type: "datetime2", nullable: false,
-                    defaultValueSql: "GETUTCDATE()"),
-                UpdatedAt = table.Column<DateTime>(type: "datetime2", nullable: true)
-            },
-            constraints: table =>
-            {
-                table.PrimaryKey("PK_{{pascalCase FEATURE_NAME}}s", x => x.Id);
-            });
-
-        // Indexes
-        migrationBuilder.CreateIndex(
-            name: "IX_{{pascalCase FEATURE_NAME}}s_Name",
-            table: "{{pascalCase FEATURE_NAME}}s",
-            column: "Name");
-
-        migrationBuilder.CreateIndex(
-            name: "IX_{{pascalCase FEATURE_NAME}}s_Status",
-            table: "{{pascalCase FEATURE_NAME}}s",
-            column: "Status");
-
-        migrationBuilder.CreateIndex(
-            name: "IX_{{pascalCase FEATURE_NAME}}s_CreatedAt",
-            table: "{{pascalCase FEATURE_NAME}}s",
-            column: "CreatedAt");
-    }
-
-    /// <inheritdoc />
-    protected override void Down(MigrationBuilder migrationBuilder)
-    {
-        migrationBuilder.DropTable(
-            name: "{{pascalCase FEATURE_NAME}}s");
-    }
-}
-
-// ============================================================
-// HOW TO CREATE A MIGRATION
-// ============================================================
-//
-// 1. Add your entity to AppDbContext:
-//
-//    public DbSet<{{pascalCase FEATURE_NAME}}> {{pascalCase FEATURE_NAME}}s => Set<{{pascalCase FEATURE_NAME}}>();
-//
-// 2. Add your configuration:
-//
-//    protected override void OnModelCreating(ModelBuilder modelBuilder)
-//    {
-//        modelBuilder.ApplyConfiguration(new {{pascalCase FEATURE_NAME}}Configuration());
-//    }
-//
-// 3. Run migration command:
-//
-//    dotnet ef migrations add Add{{pascalCase FEATURE_NAME}} -p src/{{NAMESPACE}}.Infrastructure -s src/{{NAMESPACE}}.Web
-//
-// 4. Apply migration:
-//
-//    dotnet ef database update -p src/{{NAMESPACE}}.Infrastructure -s src/{{NAMESPACE}}.Web
-//
-// ============================================================
+// ============================================================
+// EF CORE MIGRATION TEMPLATE
+// Generated by MORPH Framework
+// ============================================================
+
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace {{NAMESPACE}}.Infrastructure.Data.Migrations;
+
+/// <inheritdoc />
+public partial class Add{{pascalCase FEATURE_NAME}} : Migration
+{
+    /// <inheritdoc />
+    protected override void Up(MigrationBuilder migrationBuilder)
+    {
+        migrationBuilder.CreateTable(
+            name: "{{pascalCase FEATURE_NAME}}s",
+            columns: table => new
+            {
+                Id = table.Column<int>(type: "int", nullable: false)
+                    .Annotation("SqlServer:Identity", "1, 1"),
+                Name = table.Column<string>(type: "nvarchar(200)", maxLength: 200, nullable: false),
+                Status = table.Column<string>(type: "nvarchar(50)", maxLength: 50, nullable: false),
+                CreatedAt = table.Column<DateTime>(type: "datetime2", nullable: false,
+                    defaultValueSql: "GETUTCDATE()"),
+                UpdatedAt = table.Column<DateTime>(type: "datetime2", nullable: true)
+            },
+            constraints: table =>
+            {
+                table.PrimaryKey("PK_{{pascalCase FEATURE_NAME}}s", x => x.Id);
+            });
+
+        // Indexes
+        migrationBuilder.CreateIndex(
+            name: "IX_{{pascalCase FEATURE_NAME}}s_Name",
+            table: "{{pascalCase FEATURE_NAME}}s",
+            column: "Name");
+
+        migrationBuilder.CreateIndex(
+            name: "IX_{{pascalCase FEATURE_NAME}}s_Status",
+            table: "{{pascalCase FEATURE_NAME}}s",
+            column: "Status");
+
+        migrationBuilder.CreateIndex(
+            name: "IX_{{pascalCase FEATURE_NAME}}s_CreatedAt",
+            table: "{{pascalCase FEATURE_NAME}}s",
+            column: "CreatedAt");
+    }
+
+    /// <inheritdoc />
+    protected override void Down(MigrationBuilder migrationBuilder)
+    {
+        migrationBuilder.DropTable(
+            name: "{{pascalCase FEATURE_NAME}}s");
+    }
+}
+
+// ============================================================
+// HOW TO CREATE A MIGRATION
+// ============================================================
+//
+// 1. Add your entity to AppDbContext:
+//
+//    public DbSet<{{pascalCase FEATURE_NAME}}> {{pascalCase FEATURE_NAME}}s => Set<{{pascalCase FEATURE_NAME}}>();
+//
+// 2. Add your configuration:
+//
+//    protected override void OnModelCreating(ModelBuilder modelBuilder)
+//    {
+//        modelBuilder.ApplyConfiguration(new {{pascalCase FEATURE_NAME}}Configuration());
+//    }
+//
+// 3. Run migration command:
+//
+//    dotnet ef migrations add Add{{pascalCase FEATURE_NAME}} -p src/{{NAMESPACE}}.Infrastructure -s src/{{NAMESPACE}}.Web
+//
+// 4. Apply migration:
+//
+//    dotnet ef database update -p src/{{NAMESPACE}}.Infrastructure -s src/{{NAMESPACE}}.Web
+//
+// ============================================================

package/framework/templates/code/dotnet/feature/endpoint.cs.hbs

@@ -1,21 +1,21 @@
-using {{pascalCase PROJECT_NAME}}.Abstractions;
-using {{pascalCase PROJECT_NAME}}.Constants;
-using {{pascalCase PROJECT_NAME}}.Extensions;
-namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
-
-internal sealed class {{pascalCase SLICE_NAME}}Endpoint : IApiEndpoint
-{
-    public void MapEndpoint(IEndpointRouteBuilder app)
-    {
-        app.MapPost("{{kebabCase FEATURE_NAME}}s", async (IHandler<{{pascalCase SLICE_NAME}}Request, Result<{{pascalCase SLICE_NAME}}Response>> handler, {{pascalCase SLICE_NAME}}Request command, CancellationToken cancellationToken) =>
-        {
-            var result = await handler.HandleAsync(command, cancellationToken);
-            return result.Match(
-              onSuccess: () => Results.Ok(result.Value),
-              onFailure: error => Results.BadRequest(error));
-        })
-        .WithTags(ApiTags.{{pascalCase FEATURE_NAME}}s)
-        .Produces<{{pascalCase SLICE_NAME}}Response>(StatusCodes.Status200OK)
-        .Produces(StatusCodes.Status400BadRequest);
-    }
-}
+using {{pascalCase PROJECT_NAME}}.Abstractions;
+using {{pascalCase PROJECT_NAME}}.Constants;
+using {{pascalCase PROJECT_NAME}}.Extensions;
+namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
+
+internal sealed class {{pascalCase SLICE_NAME}}Endpoint : IApiEndpoint
+{
+    public void MapEndpoint(IEndpointRouteBuilder app)
+    {
+        app.MapPost("{{kebabCase FEATURE_NAME}}s", async (IHandler<{{pascalCase SLICE_NAME}}Request, Result<{{pascalCase SLICE_NAME}}Response>> handler, {{pascalCase SLICE_NAME}}Request command, CancellationToken cancellationToken) =>
+        {
+            var result = await handler.HandleAsync(command, cancellationToken);
+            return result.Match(
+              onSuccess: () => Results.Ok(result.Value),
+              onFailure: error => Results.BadRequest(error));
+        })
+        .WithTags(ApiTags.{{pascalCase FEATURE_NAME}}s)
+        .Produces<{{pascalCase SLICE_NAME}}Response>(StatusCodes.Status200OK)
+        .Produces(StatusCodes.Status400BadRequest);
+    }
+}

package/framework/templates/code/dotnet/feature/request.cs.hbs

@@ -1,4 +1,4 @@
-namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
-
-// TODO: Add properties matching the {{pascalCase SLICE_NAME}} command
-public sealed record {{pascalCase SLICE_NAME}}Request();
+namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
+
+// TODO: Add properties matching the {{pascalCase SLICE_NAME}} command
+public sealed record {{pascalCase SLICE_NAME}}Request();

package/framework/templates/code/dotnet/feature/response.cs.hbs

@@ -1,4 +1,4 @@
-namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
-
-// TODO: Add properties matching the {{pascalCase SLICE_NAME}} response
-public sealed record {{pascalCase SLICE_NAME}}Response(Guid Id);
+namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
+
+// TODO: Add properties matching the {{pascalCase SLICE_NAME}} response
+public sealed record {{pascalCase SLICE_NAME}}Response(Guid Id);

package/framework/templates/code/dotnet/feature/validator.cs.hbs

@@ -1,15 +1,15 @@
-using FluentValidation;
-
-namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
-
-public class {{pascalCase SLICE_NAME}}Validator : AbstractValidator<{{pascalCase SLICE_NAME}}Request>
-{
-    public {{pascalCase SLICE_NAME}}Validator()
-    {
-        // TODO: Add validation rules for {{pascalCase SLICE_NAME}}Request properties
-        // Example:
-        // RuleFor(c => c.Name)
-        //     .NotEmpty().WithMessage("Name is required")
-        //     .MaximumLength(200).WithMessage("Name must not exceed 200 characters");
-    }
-}
+using FluentValidation;
+
+namespace {{pascalCase PROJECT_NAME}}.Features.{{pascalCase FEATURE_NAME}}Feature.{{pascalCase SLICE_NAME}};
+
+public class {{pascalCase SLICE_NAME}}Validator : AbstractValidator<{{pascalCase SLICE_NAME}}Request>
+{
+    public {{pascalCase SLICE_NAME}}Validator()
+    {
+        // TODO: Add validation rules for {{pascalCase SLICE_NAME}}Request properties
+        // Example:
+        // RuleFor(c => c.Name)
+        //     .NotEmpty().WithMessage("Name is required")
+        //     .MaximumLength(200).WithMessage("Name must not exceed 200 characters");
+    }
+}

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;