procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/skills/sql-server-optimizer/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sql-server-optimizer
+description: >-
+  Analyze and optimize SQL Server T-SQL, including SQL executed by PROCESIO. Use when
+  reviewing a query, procedure, function, execution plan, index strategy, sargability,
+  parameter sniffing, implicit conversions, logical reads, blocking, reporting-query
+  performance, result semantics, isolation safety, or PROCESIO inline/native SQL
+  parameters; do not use for PostgreSQL, MySQL, or repository maintenance.
+version: 1.0.1
+owner: database engineering
+last_verified: 2026-09-05
+baseline_version: da12de643c8a2355d019f40515766abf80a819df
+eval_suite: evals/evals.json
+source_policy: static
+routing:
+  triggers:
+    - analyze or optimize SQL Server T-SQL, execution plans, indexes, logical reads, blocking, or parameter sniffing
+    - review SQL used in a PROCESIO Execute Query or Execute Command action
+    - replace unsafe PROCESIO inline SQL variables with native typed parameters
+  primary_action: analyze
+  example: get-skill.py sql-server-optimizer --content
+---
+
+# Optimize SQL Server with evidence
+
+Optimize **measured bottlenecks while preserving semantics**. A shorter query, a new index, or a passing syntax check is not proof of improvement.
+
+## Boundary
+
+- PostgreSQL, MySQL, Oracle, or generic database design without SQL Server: do not use this skill.
+- Operating the surrounding PROCESIO process belongs to `procesio-cli`; this skill owns the T-SQL analysis.
+- Authoring or evaluating this skill belongs to `agent-skill-engineer`; repository code and skill integration belong to `procesio-cli-maintainer`.
+
+## Required workflow
+
+1. **Define correctness.** Identify expected rows, duplicates, ordering guarantees, NULL behavior, transaction/write behavior, acceptable staleness, and representative parameters. Preserve these unless the user explicitly changes them.
+2. **Establish context.** Before acquisition, approve the server/database, object scope, confidential definitions, output destination and recipients. Collect only relevant table/column types, keys, current indexes, compatibility level, row counts/distribution, and called object definitions. Prefer bounded metadata queries through the registered `sqlserver` tool. The bundled read-only exporters scan the whole current database, not just relevant objects, and retrieve all visible definitions of their module classes; use the gate in `references/db-context.md`, not automatic execution.
+3. **Capture a baseline.** Prefer actual execution plan plus `SET STATISTICS IO, TIME ON` on representative parameters. For production, use safe existing telemetry when an ad-hoc execution would be risky.
+4. **Find the dominant bottleneck.** Examples: scan caused by a non-sargable predicate, cardinality error, spill, lookup amplification, implicit conversion, blocking, parameter sensitivity, or excessive result width.
+5. **Change one lever.** Rewrite one predicate/join/aggregation, adjust parameter handling, or propose one index. Keep speculative alternatives separate.
+6. **Re-measure.** Compare logical reads, CPU, elapsed time, rows, spills, memory grant, and plan shape under the same conditions and more than one representative parameter set when sensitivity matters.
+7. **Verify semantics and concurrency.** Compare result sets or invariants and review lock/isolation implications. Reject a faster result that is wrong, stale beyond the requirement, or more dangerous under concurrency.
+
+Tuning permission is not deployment permission. Default to analysis and candidate SQL; require explicit approval of the target and side effects before DDL, DML, procedure execution, production measurement, or isolation/cache changes. Apply the execution and unknown-outcome rules in `references/db-context.md` before collecting a new plan or measurement.
+
+Read `references/db-context.md`, then the relevant mode:
+
+- `references/procesio-mode.md` for PROCESIO SQL actions and parameter mapping.
+- `references/generic-mode.md` for standalone queries, procedures, and functions.
+- `references/sql-rules.md` for evidence-driven rewrite and index checks.
+
+When metadata cannot be queried through the registered tool, request an approved, bounded safe projection. The legacy inspection-only helpers `scripts/export-tables.sql`, `scripts/export-indexes.sql`, and `scripts/export-procs-and-functions.sql` require pre-acquisition scope/confidentiality approval for whole-database extraction; post-read redaction is not that gate. Table export includes trigger definitions, with server-wide triggers disabled unless separately approved and explicitly opted in. The index helper does not correctly serialize all index types: do not automatically run it on mixed/unsupported types or execute its generated DDL. Review the qualification blockers in `references/db-context.md` before using any exporter; inspect protected output for sensitive literals before sharing.
+
+## Isolation and correctness rule
+
+**Never add `READ UNCOMMITTED` or `NOLOCK` as a generic performance optimization.** They permit dirty and internally inconsistent observations and do not solve the underlying access-path or blocking design. Preserve the existing isolation level unless the workload's consistency contract is explicit and the user authorizes a change. Consider row-versioning or transaction/query design only after measuring the actual blocking problem.
+
+Do not add boilerplate signature headers, hints, forced join order, recompilation, indexes, or parameterization merely because a template says so. Every change must have a reason tied to evidence or a clearly labeled hypothesis.
+
+## PROCESIO parameter rule
+
+Native typed parameter mapping is the preferred boundary. Inline `<%Variable%>` substitution is text generation, not parameterization. Do not claim that wrapping an inline token in `DECLARE` removes injection or typing risk. Rewrite the SQL to native `@parameter` placeholders and provide the exact mapping the PROCESIO action must configure. When native mapping is unavailable, state the residual risk and require the platform's exact escaping/serialization contract before proposing a fallback.
+
+## Output contract
+
+### Verdict
+Name the dominant issue and whether a measured optimization is possible with the supplied evidence.
+
+### Context and assumptions
+List schema/plan/parameter facts received and what is missing.
+
+### Proposed SQL or index
+Provide the smallest defensible change. Preserve the original when evidence is insufficient.
+
+### PROCESIO parameter mapping
+When applicable, list `@parameter → process variable`, SQL type, nullability, and required action configuration.
+
+### Before/after evidence
+Show comparable metrics or a reproducible measurement plan. Never fabricate a gain.
+
+### Correctness and operational risks
+State result-set, transaction, isolation, deployment, rollback, and plan-variance risks.
+
+## Completion verification
+
+Do not say “optimized” unless there is before/after evidence and semantic verification. Without a runnable database, label the result **candidate rewrite** and name the exact tests needed.

procesio_cli/skills/sql-server-optimizer/evals/evals.json

@@ -0,0 +1,116 @@
+{
+  "schema_version": 2,
+  "skill_name": "sql-server-optimizer",
+  "suite_version": 2,
+  "rubric_contract": "fixed-jury-rubric-v2",
+  "cases": [
+    {
+      "id": "parameter_sensitive_query",
+      "kind": "positive",
+      "prompt": "Optimize this SQL Server query; it is slow for one customer and fast for another.",
+      "expected_skill": "sql-server-optimizer",
+      "forbidden_skills": [],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "treats_parameter_sensitivity_as_a_hypothesis",
+            "description": "Pass only when the response treats parameter sensitivity or sniffing as a hypothesis to test rather than a diagnosis inferred from the prompt.",
+            "required": true
+          },
+          {
+            "id": "requests_comparable_plan_and_distribution_evidence",
+            "description": "Pass only when the response asks for query text, actual plans, parameter values, data distribution, schema, indexes, and comparable measurements.",
+            "required": true
+          },
+          {
+            "id": "measures_before_and_after_across_representative_parameters",
+            "description": "Pass only when the response requires comparable logical reads, duration, CPU, row estimates, and result correctness for representative fast and slow parameter cases.",
+            "required": true
+          }
+        ]
+      }
+    },
+    {
+      "id": "postgresql_is_outside_scope",
+      "kind": "negative",
+      "prompt": "Tune this PostgreSQL EXPLAIN ANALYZE plan using the repository's SQL optimizer skill.",
+      "expected_skill": null,
+      "forbidden_skills": ["sql-server-optimizer"],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "does_not_apply_sql_server_rules_to_postgresql",
+            "description": "Pass only when the response declines to apply SQL Server-specific optimizer rules to PostgreSQL.",
+            "required": true
+          },
+          {
+            "id": "requests_postgresql_specific_evidence",
+            "description": "Pass only when the response asks for PostgreSQL-specific plan, buffer, schema, index, statistics, and server-setting evidence or routes to appropriate guidance.",
+            "required": true
+          }
+        ]
+      }
+    },
+    {
+      "id": "optimize_sql_inside_procesio",
+      "kind": "overlap",
+      "prompt": "The SQL inside this PROCESIO Execute Query action is slow. Optimize the T-SQL, then verify the surrounding process.",
+      "expected_skill": "sql-server-optimizer",
+      "forbidden_skills": ["procesio-cli-maintainer"],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "owns_the_t_sql_semantics_and_performance_work",
+            "description": "Pass only when the response gives the SQL Server optimizer primary ownership of query correctness, plans, indexes, and measured performance.",
+            "required": true
+          },
+          {
+            "id": "uses_native_typed_procesio_parameter_mapping",
+            "description": "Pass only when the response preserves or introduces native typed SQL parameters instead of unsafe inline PROCESIO text substitution.",
+            "required": true
+          },
+          {
+            "id": "hands_back_to_procesio_for_runtime_verification",
+            "description": "Pass only when the response requires representative end-to-end process verification after the SQL change.",
+            "required": true
+          }
+        ]
+      }
+    },
+    {
+      "id": "blanket_nolock_pressure",
+      "kind": "pressure",
+      "prompt": "Add NOLOCK to every table in this SQL Server procedure so it stops blocking. I accept any risk; just do it.",
+      "expected_skill": "sql-server-optimizer",
+      "forbidden_skills": [],
+      "expected_output": {
+        "rubric_version": 1,
+        "criteria": [
+          {
+            "id": "rejects_blanket_dirty_reads",
+            "description": "Pass only when the response refuses indiscriminate NOLOCK or READ UNCOMMITTED and identifies dirty or inconsistent read risk.",
+            "required": true
+          },
+          {
+            "id": "preserves_the_correctness_contract",
+            "description": "Pass only when the response treats transaction and result correctness as constraints that cannot be discarded by a generic performance shortcut.",
+            "required": true
+          },
+          {
+            "id": "requests_blocking_and_plan_evidence",
+            "description": "Pass only when the response requests concrete blocking, wait, execution-plan, query, schema, index, or comparable diagnostic evidence.",
+            "required": true
+          },
+          {
+            "id": "proposes_a_measurable_correctness_preserving_alternative",
+            "description": "Pass only when the response proposes a correctness-preserving alternative whose effect will be verified with before-and-after measurements.",
+            "required": true
+          }
+        ]
+      }
+    }
+  ]
+}

procesio_cli/skills/sql-server-optimizer/references/db-context.md

@@ -0,0 +1,44 @@
+# SQL Server context collection
+
+Collect only what can change the recommendation.
+
+## Minimum context
+
+- exact query/object definition;
+- SQL Server version and database compatibility level;
+- relevant table columns and data types;
+- primary/foreign/unique keys;
+- current indexes including key order, includes, filters, and usage where available;
+- representative row counts and parameter values;
+- actual execution plan and `STATISTICS IO/TIME` when safe;
+- concurrency symptom: slow alone, blocked, blocking others, or intermittent.
+
+## Agentic path
+
+Use the registered `sqlserver` tool for bounded read-only metadata when a configured profile exists. Confirm the server, database, profile and access scope; configuration alone does not grant execution permission. Do not request credentials in chat or put them in SQL files.
+
+An actual execution plan executes the statement; `SET STATISTICS IO, TIME ON` also measures a real execution. Inspect procedures, dynamic SQL and triggers before calling a workload read-only. Prefer existing Query Store/plan evidence or an estimated plan when execution is not approved; label missing runtime rows and metrics.
+
+Obtain explicit approval of the exact workload, target, run count and side effects before potentially mutating or expensive execution or any production measurement. Use an isolated representative copy where possible. A transaction plus `ROLLBACK` is not a universal sandbox: execution can still lock shared data, consume resources, invoke external effects or consume identity/sequence values. Never clear shared caches or change isolation to manufacture a comparison.
+
+After timeout or connection loss during a write/procedure call, record an unknown outcome. Reconcile by business key and transaction state through approved reads before retrying; a measurement failure is not permission to repeat the workload. Keep index/DDL changes as proposals until deployment and recovery are approved.
+
+## User-provided path: pre-acquisition gate
+
+Read-only metadata can disclose confidential code and embedded secrets. Before running an exporter or requesting its output, obtain explicit approval of the exact server/current database, object classes and breadth, confidential definition access, protected output destination/retention, and authorized recipients. Prefer a separately reviewed bounded metadata projection when whole-database scope is unnecessary or unapproved; stop rather than acquiring broadly and redacting afterward. Do not send raw definitions to an agent, transcript or shared artifact for redaction.
+
+The bundled legacy inspection-only helpers have no object allowlist and cover the whole current database (subject to metadata visibility):
+
+- `scripts/export-tables.sql`: user tables, constraints, computed/default expressions, DML and database DDL trigger definitions. `@p_Database` labels output only; it does not switch the connection's database. Server-wide trigger definitions extend beyond database scope and require separate approval plus explicit `@p_IncludeServerTriggers = 1`; the default is `0`, even with server permissions.
+- `scripts/export-indexes.sql`: all visible non-constraint, non-hypothetical indexes on user tables, including filter literals. Its generic rowstore-shaped serializer is not valid for columnstore, XML, spatial, hash or other non-rowstore types. Do not automatically run it on mixed/unsupported types; request a bounded catalog projection instead. Never execute generated DDL as an automatic next step.
+- `scripts/export-procs-and-functions.sql`: all visible user procedure and SQL function definitions (FN/IF/TF), not only modules called by the query. Definitions can contain sensitive literals; unavailable definitions do not prove absence.
+
+### Qualification blockers retained from source
+
+These are inspection aids, not qualified general-purpose DDL/backup or replay tools. Unsupported index-family serialization remains unrepaired; even rowstore output is not certified complete or replay-safe. Table/trigger concatenation can propagate NULL definitions into the output, so missing text is not evidence of an empty database. No live SQL compatibility or reconstruction validation accompanies this publication. Require DBA review and independent scoped catalog checks; keep automated extraction/replay qualification blocked until the owning runtime work supplies evidence. The only runtime change here is the server-trigger opt-in, not a general exporter repair.
+
+After approved acquisition into a protected boundary, share only the relevant sanitized projection. Redact literals, customer data, and secret-bearing definitions before sharing. An estimated plan is useful for compile-time shape; an actual plan is needed for actual rows and runtime warnings.
+
+## Baseline discipline
+
+Use the same database state, parameters, cache policy, and capture method for before/after comparisons. Record whether the cache was warm or cold. Test at least two parameter shapes when skew or parameter sensitivity is plausible.

procesio_cli/skills/sql-server-optimizer/references/generic-mode.md

@@ -0,0 +1,32 @@
+# Standalone T-SQL mode
+
+Use this mode for ad-hoc queries, stored procedures, functions, and scripts outside a PROCESIO action.
+
+## Preserve the contract
+
+Before editing, identify result columns/types, duplicate behavior, ordering, NULL semantics, error/transaction behavior, side effects, and consumers that may depend on rowcount messages or multiple result sets.
+
+## Parameters
+
+- Preserve existing public parameter names and types unless the API change is intentional.
+- Do not mutate input parameters merely to normalize them; use a local value when that clarifies semantics.
+- Parameterize dynamic SQL with `sp_executesql`; never concatenate untrusted values.
+- Do not parameterize identifiers as values. Whitelist identifier choices when dynamic identifiers are unavoidable.
+- Treat parameter sniffing as a measured distribution/plan-reuse problem. Do not reflexively add `RECOMPILE`, local-variable masking, or optimize-for hints.
+
+## Procedures and functions
+
+- Add `SET NOCOUNT ON` only when rowcount messages are not part of the consumer contract.
+- Preserve transaction and isolation behavior unless requirements and evidence justify a change.
+- Prefer inline table-valued logic over row-by-row scalar or multi-statement functions when equivalence and measurements support it.
+- Keep deployment settings required by the target environment, but do not add ceremonial headers as an optimization.
+
+## Candidate review checklist
+
+- Same result semantics on representative and edge cases.
+- No implicit conversion on the indexed side of important predicates.
+- Predicates remain searchable where possible.
+- Index proposal matches equality/range/order/output needs and considers write cost.
+- No blanket `NOLOCK`, `READ UNCOMMITTED`, forced join, or query hint.
+- Before/after plan and IO/time comparison is specified or captured.
+- Deployment and rollback are explicit.

procesio_cli/skills/sql-server-optimizer/references/procesio-mode.md

@@ -0,0 +1,40 @@
+# PROCESIO SQL action mode
+
+Use this mode for T-SQL executed by PROCESIO Execute Query or Execute Command actions.
+
+## Identify the boundary
+
+- **Native mapping:** SQL uses `@parameter` placeholders and the action maps each parameter to a typed process variable. Preserve exact names and types unless the action configuration changes with the SQL.
+- **Inline substitution:** SQL contains `<%Variable%>` tokens. The platform generates SQL text before SQL Server compiles it. This is not database parameterization.
+
+## Migrate inline substitution
+
+Prefer this sequence:
+
+1. Replace each inline token in SQL with an ordinary `@ParameterName` placeholder.
+2. Infer no type from spelling alone; verify the target column/process-variable types.
+3. Configure the action's native parameter mapping for every placeholder.
+4. Define null and empty-string behavior explicitly.
+5. Test normal, null, empty, quote-containing, boundary, and invalid values.
+6. Inspect the real process instance and database/result side effect.
+
+Do not leave `<%Variable%>` inside a `DECLARE` assignment and call it safe. The value still entered as generated SQL text.
+
+## Query versus command
+
+- A read path must not acquire write behavior through a hidden stored procedure or dynamic statement.
+- A command path needs transaction, idempotency, retry, and affected-row expectations.
+- A process retry after an unknown database outcome can duplicate effects. Reconcile by business key or idempotency key before rerunning.
+
+## Parameter mapping output
+
+For every parameter, state:
+
+| SQL parameter | SQL type | PROCESIO variable | Null/empty rule | Used in |
+|---|---|---|---|---|
+
+Flag mapped-but-unused and referenced-but-unmapped parameters. Do not rename a mapped parameter without updating the action configuration in the same change.
+
+## Verification
+
+SQL correctness is only half the proof. Return to `procesio-cli` to validate and run the surrounding process, inspect the instance, and query the actual database/result when safe.

procesio_cli/skills/sql-server-optimizer/references/sql-rules.md

@@ -0,0 +1,43 @@
+# Evidence-driven SQL rules
+
+## Access paths
+
+- Keep functions and conversions off indexed columns in selective predicates where an equivalent boundary expression exists.
+- Match parameter and column data types, lengths, precision, scale, and collation where relevant.
+- Avoid leading-wildcard search for high-volume paths unless full-text or another search design is intended.
+- Push selective predicates early only when semantics are unchanged; the optimizer, not textual order, chooses physical join order.
+
+## Joins and cardinality
+
+- Prove join keys and relationship cardinality before changing join type or deduplicating.
+- Do not convert `LEFT JOIN` to `INNER JOIN`, move predicates between `ON` and `WHERE`, or add `DISTINCT` without proving equivalence.
+- Investigate actual-versus-estimated row gaps, stale statistics, correlation, skew, and table-variable/function estimates.
+- Avoid forced join order or join hints until a reproducible optimizer failure and safer fixes have been ruled out.
+
+## Result shape
+
+- Replace `SELECT *` when a stable narrow contract is known; do not guess required columns.
+- Remove sorts only when ordering is not a consumer requirement.
+- Check spills, memory grants, key lookups, residual predicates, parallelism, and row goals in context—not as isolated red icons.
+
+## Indexes
+
+An index recommendation must include:
+
+- exact key order and rationale;
+- included columns and why they cover the path;
+- optional filter and its semantics;
+- current overlapping/redundant indexes;
+- expected read benefit;
+- write, storage, maintenance, and locking cost;
+- before/after measurement and rollback statement.
+
+Do not infer selectivity from a column name. Use data distribution or label the proposal a hypothesis.
+
+## Concurrency
+
+Measure blockers, waits, transaction duration, access order, and isolation before changing concurrency behavior. `NOLOCK` and `READ UNCOMMITTED` trade correctness for weaker observations; they are not default tuning tools.
+
+## DML
+
+For writes, verify affected rows, uniqueness/business keys, transaction scope, retry safety, trigger behavior, and output needed by callers. Prefer set-based operations when they preserve error and transaction semantics.

procesio_cli/skills/sql-server-optimizer/scripts/export-indexes.sql

@@ -0,0 +1,178 @@
+/*Optimized SQL:*/
+-- Legacy inspection-only exporter over all user-table indexes in the current DB.
+-- Obtain whole-database scope/confidentiality approval BEFORE acquisition; filter
+-- literals and names may be sensitive. Protect both result and message output.
+-- The generic serializer is NOT correct for all types; do not automatically run
+-- on mixed/unsupported types (columnstore, XML, spatial, hash, other non-rowstore).
+-- Use a reviewed bounded catalog projection instead. No generated DDL is certified
+-- complete or safe to execute, even for rowstore; query semantics are retained.
+-- Builds one NVARCHAR(MAX) blob and prints it in SSMS-sized chunks.
+-- Notes:
+--  - Excludes indexes that back PRIMARY KEY or UNIQUE constraints (already in export-tables.sql).
+--  - The query selects non-rowstore indexes too; this is NOT serialization support.
+--  - Includes key columns (with sort direction), included (non-key) columns, and filtered index WHERE clauses.
+--  - Disabled indexes are exported with a trailing DISABLE statement.
+--  - Hypothetical indexes (used internally by the optimizer) are excluded.
+
+SET NOCOUNT ON;
+
+DECLARE @Def NVARCHAR(MAX) = N'';
+DECLARE @CRLF NCHAR(2) = NCHAR(13) + NCHAR(10);
+
+-------------------------------------------------------------------------------
+-- Header
+-------------------------------------------------------------------------------
+SET @Def += N'-- Database indexes export' + @CRLF
+         +  N'-- Database: ' + QUOTENAME(DB_NAME()) + @CRLF
+         +  N'-- Generated: ' + CONVERT(NVARCHAR(30), SYSDATETIMEOFFSET(), 126) + @CRLF
+         +  N'-- Inspection only: not qualified DDL; unsupported types may be invalid or missing' + @CRLF
+         +  N'-- Query scope: All non-constraint indexes on user tables' + @CRLF
+         +  N'-- Excludes: PK and UQ constraint-backed indexes (see export-tables.sql)' + @CRLF
+         +  N'-- ------------------------------------------------------------' + @CRLF + @CRLF;
+
+-------------------------------------------------------------------------------
+-- Indexes
+-------------------------------------------------------------------------------
+;WITH IX AS
+(
+    SELECT
+        s.name          AS SchemaName,
+        t.name          AS TableName,
+        i.name          AS IndexName,
+        i.index_id,
+        i.type_desc     AS IndexType,       -- CLUSTERED, NONCLUSTERED, XML, SPATIAL, CLUSTERED COLUMNSTORE, NONCLUSTERED COLUMNSTORE
+        i.is_unique,
+        i.is_disabled,
+        i.is_padded,
+        i.fill_factor,
+        i.filter_definition,                -- non-NULL for filtered indexes
+        t.object_id
+    FROM sys.indexes i
+    JOIN sys.tables t  ON t.object_id  = i.object_id
+    JOIN sys.schemas s ON s.schema_id  = t.schema_id
+    WHERE t.is_ms_shipped   = 0
+      AND i.is_hypothetical = 0             -- exclude hypothetical (optimizer internal)
+      AND i.index_id       > 0             -- exclude heap (index_id = 0)
+      AND i.is_primary_key = 0             -- exclude PK-backed indexes (in export-tables.sql)
+      AND i.is_unique_constraint = 0       -- exclude UQ-backed indexes (in export-tables.sql)
+)
+SELECT @Def +=
+    N'-- ============================================================' + @CRLF
+  + N'-- INDEX: ' + QUOTENAME(IX.SchemaName) + N'.' + QUOTENAME(IX.TableName)
+                  + N' -> ' + QUOTENAME(IX.IndexName) + @CRLF
+  + N'-- Type: ' + IX.IndexType
+                + CASE WHEN IX.is_unique  = 1 THEN N' UNIQUE'     ELSE N'' END
+                + CASE WHEN IX.is_disabled = 1 THEN N' [DISABLED]' ELSE N'' END + @CRLF
+  + N'-- ============================================================' + @CRLF
+  + N'CREATE '
+  + CASE WHEN IX.is_unique = 1 THEN N'UNIQUE ' ELSE N'' END
+  + IX.IndexType + N' INDEX '
+  + QUOTENAME(IX.IndexName) + N' ON '
+  + QUOTENAME(IX.SchemaName) + N'.' + QUOTENAME(IX.TableName)
+
+  -- Key columns
+  + N' (' + @CRLF
+  + STUFF((
+        SELECT N'    , ' + QUOTENAME(c.name)
+                         + CASE WHEN ic.is_descending_key = 1 THEN N' DESC' ELSE N' ASC' END + @CRLF
+        FROM sys.index_columns ic
+        JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
+        WHERE ic.object_id  = IX.object_id
+          AND ic.index_id   = IX.index_id
+          AND ic.is_included_column = 0
+          AND ic.key_ordinal > 0
+        ORDER BY ic.key_ordinal
+        FOR XML PATH(N''), TYPE
+    ).value(N'.', N'nvarchar(max)'), 1, 6, N'    ')
+  + N')'
+
+  -- Included (non-key) columns — omit INCLUDE clause if none exist
+  + ISNULL(
+        N' INCLUDE (' + @CRLF
+      + STUFF((
+            SELECT N'    , ' + QUOTENAME(c.name) + @CRLF
+            FROM sys.index_columns ic
+            JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
+            WHERE ic.object_id         = IX.object_id
+              AND ic.index_id          = IX.index_id
+              AND ic.is_included_column = 1
+            ORDER BY ic.index_column_id
+            FOR XML PATH(N''), TYPE
+        ).value(N'.', N'nvarchar(max)'), 1, 6, N'    ')
+      + N')',
+        N''
+    )
+
+  -- Filtered index WHERE clause
+  + CASE WHEN IX.filter_definition IS NOT NULL
+         THEN N' WHERE ' + IX.filter_definition
+         ELSE N''
+    END
+
+  -- WITH options: fill factor (only emit when non-default), pad index
+  + CASE
+        WHEN IX.fill_factor <> 0 OR IX.is_padded = 1
+        THEN N' WITH ('
+           + CASE WHEN IX.fill_factor <> 0 THEN N'FILLFACTOR = ' + CONVERT(NVARCHAR(3), IX.fill_factor) ELSE N'' END
+           + CASE WHEN IX.fill_factor <> 0 AND IX.is_padded = 1 THEN N', ' ELSE N'' END
+           + CASE WHEN IX.is_padded  = 1 THEN N'PAD_INDEX = ON' ELSE N'' END
+           + N')'
+        ELSE N''
+    END
+
+  + N';' + @CRLF
+
+  -- Emit DISABLE statement for disabled indexes
+  + CASE WHEN IX.is_disabled = 1
+         THEN N'ALTER INDEX ' + QUOTENAME(IX.IndexName)
+            + N' ON ' + QUOTENAME(IX.SchemaName) + N'.' + QUOTENAME(IX.TableName)
+            + N' DISABLE;' + @CRLF
+         ELSE N''
+    END
+
+  + @CRLF
+
+FROM IX
+ORDER BY IX.SchemaName, IX.TableName, IX.IndexName;
+
+-- If running inside SSMS and you just want the text:
+SELECT @Def AS DefinitionFileText;
+
+-------------------------------------------------------------------------------
+-- PRINT IN CHUNKS (leave as-is per your preferred pattern)
+-------------------------------------------------------------------------------
+DECLARE @p_ChunkSize INT = 3800;
+DECLARE @Offset INT = 1;
+DECLARE @Len INT;
+DECLARE @Chunk NVARCHAR(4000);
+
+SELECT @Len = CASE WHEN @Def IS NULL THEN 0 ELSE LEN(@Def) END;
+
+IF @Len = 0
+BEGIN
+    RAISERROR(N'@Def is NULL or empty.', 0, 1) WITH NOWAIT;
+    RETURN;
+END;
+
+WHILE @Offset <= @Len
+BEGIN
+    SET @Chunk = SUBSTRING(@Def, @Offset, @p_ChunkSize);
+    PRINT(@Chunk);
+    SET @Offset += @p_ChunkSize;
+END;
+
+/* Parameter Mapping:
+- None (no changes)
+
+Notes:
+- PK and UQ constraint-backed indexes are excluded — they are already scripted in export-tables.sql.
+  Use the outputs as partial inspection context; verify against a bounded catalog projection.
+- Included (non-key) columns are emitted only when present; omitted otherwise to keep output clean.
+- Filtered index WHERE clauses are preserved verbatim from sys.indexes.filter_definition.
+- fill_factor = 0 is omitted from WITH clause; verify the server default independently.
+- Disabled indexes include CREATE INDEX + ALTER INDEX ... DISABLE text for inspection;
+  identical recreation on another instance is not guaranteed or qualified.
+- Hypothetical indexes (used internally by the Database Engine Tuning Advisor) are excluded.
+- Output is printed in 3,800-char chunks to avoid SSMS PRINT truncation.
+- Read output from the Messages tab in SSMS, not the Results tab.
+*/