@aws/ml-container-creator 0.3.0 → 0.5.0

package/bin/cli.js

@@ -98,6 +98,9 @@ program
     .addOption(new Option('--include-sample', 'Include sample model code'))
     .addOption(new Option('--include-testing', 'Include test suite'))
     .addOption(new Option('--test-types <types>', 'Comma-separated test types'))
+    .addOption(new Option('--enable-lora', 'Enable LoRA adapter serving (transformers with vllm/sglang/djl-lmi only)'))
+    .addOption(new Option('--max-loras <n>', 'Maximum concurrent LoRA adapters in GPU memory (default: 30)'))
+    .addOption(new Option('--max-lora-rank <n>', 'Maximum LoRA rank (default: 64)'))
 
     // --- MCP & Discovery ---
     .addOption(new Option('--smart', 'Enable Bedrock-powered smart mode on MCP servers'))
@@ -190,7 +193,7 @@ program.configureHelp({
                 groups.env.push(opt);
             } else if (['--hf-token', '--hf-token-arn', '--ngc-token', '--ngc-token-arn'].includes(long)) {
                 groups.auth.push(opt);
-            } else if (['--include-sample', '--include-testing', '--test-types'].includes(long)) {
+            } else if (['--include-sample', '--include-testing', '--test-types', '--enable-lora', '--max-loras', '--max-lora-rank'].includes(long)) {
                 groups.features.push(opt);
             } else if (['--smart', '--discover'].includes(long)) {
                 groups.mcp.push(opt);
@@ -307,7 +310,6 @@ program
 program
     .command('registry')
     .description('Registry operations (list, get, remove, replay, export, import, search) — experimental, may be reconciled with do/register')
-    .passThroughOptions()
     .argument('<action>', 'Registry action (log, list, get, remove, replay, export, import, search)')
     .argument('[args...]', 'Additional arguments')
     .option('--backend <backend>', 'Filter by backend')
@@ -328,6 +330,7 @@ program
     .option('--notes <text>', 'Deployment notes')
     .option('--project', 'Use project-level registry')
     .option('--parameters <json>', 'Parameters JSON string')
+    .option('--ic-list <json>', 'IC list JSON string')
     .option('--generator-version <version>', 'Generator version')
     // Options used by `registry list-architectures`
     .option('--server <name>', 'Filter by server name (for list-architectures)')

package/config/bootstrap-stack.json

@@ -67,6 +67,37 @@
                   ],
                   "Resource": "*"
                 },
+                {
+                  "Sid": "SageMakerBenchmarking",
+                  "Effect": "Allow",
+                  "Action": [
+                    "sagemaker:CreateAIBenchmarkJob",
+                    "sagemaker:DescribeAIBenchmarkJob",
+                    "sagemaker:ListAIBenchmarkJobs",
+                    "sagemaker:StopAIBenchmarkJob",
+                    "sagemaker:DeleteAIBenchmarkJob",
+                    "sagemaker:CreateAIWorkloadConfig",
+                    "sagemaker:DescribeAIWorkloadConfig",
+                    "sagemaker:ListAIWorkloadConfigs",
+                    "sagemaker:DeleteAIWorkloadConfig",
+                    "sagemaker:CreateTrainingJob",
+                    "sagemaker:DescribeTrainingJob",
+                    "sagemaker:StopTrainingJob",
+                    "sagemaker:AddTags"
+                  ],
+                  "Resource": "*"
+                },
+                {
+                  "Sid": "PassRoleToSageMaker",
+                  "Effect": "Allow",
+                  "Action": "iam:PassRole",
+                  "Resource": { "Fn::Sub": "arn:aws:iam::${AWS::AccountId}:role/mlcc-sagemaker-execution-role" },
+                  "Condition": {
+                    "StringEquals": {
+                      "iam:PassedToService": "sagemaker.amazonaws.com"
+                    }
+                  }
+                },
                 {
                   "Sid": "ECRPull",
                   "Effect": "Allow",
@@ -76,7 +107,7 @@
                     "ecr:GetDownloadUrlForLayer",
                     "ecr:BatchGetImage"
                   ],
-                  "Resource": { "Fn::Sub": "arn:aws:ecr:*:${AWS::AccountId}:repository/ml-container-creator" }
+                  "Resource": "*"
                 },
                 {
                   "Sid": "ECRAuth",
@@ -99,6 +130,7 @@
                   "Effect": "Allow",
                   "Action": [
                     "s3:GetObject",
+                    "s3:PutObject",
                     "s3:ListBucket"
                   ],
                   "Resource": [
@@ -113,12 +145,36 @@
                     "secretsmanager:GetSecretValue",
                     "secretsmanager:DescribeSecret"
                   ],
-                  "Resource": "arn:aws:secretsmanager:*:*:secret:mlcc/*",
-                  "Condition": {
-                    "StringEquals": {
-                      "aws:ResourceTag/mlcc:managed-by": "ml-container-creator"
-                    }
-                  }
+                  "Resource": [
+                    "arn:aws:secretsmanager:*:*:secret:mlcc/*",
+                    "arn:aws:secretsmanager:*:*:secret:ml-container-creator/*"
+                  ]
+                },
+                {
+                  "Sid": "SecretsManagerWrite",
+                  "Effect": "Allow",
+                  "Action": [
+                    "secretsmanager:CreateSecret",
+                    "secretsmanager:PutSecretValue",
+                    "secretsmanager:TagResource"
+                  ],
+                  "Resource": [
+                    "arn:aws:secretsmanager:*:*:secret:mlcc/*",
+                    "arn:aws:secretsmanager:*:*:secret:ml-container-creator/*"
+                  ]
+                },
+                {
+                  "Sid": "QuotaAndAvailability",
+                  "Effect": "Allow",
+                  "Action": [
+                    "service-quotas:GetServiceQuota",
+                    "service-quotas:ListServiceQuotas",
+                    "ec2:DescribeCapacityReservations",
+                    "sagemaker:ListTrainingPlans",
+                    "sagemaker:DescribeTrainingPlan",
+                    "sagemaker:ListEndpoints"
+                  ],
+                  "Resource": "*"
                 }
               ]
             }
@@ -185,6 +241,25 @@
           { "Key": "mlcc:created-by", "Value": "bootstrap" }
         ]
       }
+    },
+
+    "BenchmarkS3Bucket": {
+      "Type": "AWS::S3::Bucket",
+      "DeletionPolicy": "Retain",
+      "UpdateReplacePolicy": "Retain",
+      "Properties": {
+        "BucketName": { "Fn::Sub": "ml-container-creator-benchmark-${AWS::Region}-${AWS::AccountId}" },
+        "VersioningConfiguration": { "Status": "Enabled" },
+        "BucketEncryption": {
+          "ServerSideEncryptionConfiguration": [
+            { "ServerSideEncryptionByDefault": { "SSEAlgorithm": "AES256" } }
+          ]
+        },
+        "Tags": [
+          { "Key": "mlcc:managed-by", "Value": "ml-container-creator" },
+          { "Key": "mlcc:created-by", "Value": "bootstrap" }
+        ]
+      }
     }
   },
 
@@ -217,6 +292,10 @@
       "Description": "S3 bucket for batch transform I/O",
       "Value": { "Ref": "BatchS3Bucket" }
     },
+    "BenchmarkS3BucketName": {
+      "Description": "S3 bucket for benchmark results output",
+      "Value": { "Ref": "BenchmarkS3Bucket" }
+    },
     "StackVersion": {
       "Description": "Bootstrap stack template version for forward compatibility tracking",
       "Value": "2026-05-04"

package/config/defaults.json

@@ -12,7 +12,7 @@
     "awsRegion": "us-east-1",
     "includeTesting": true,
     "testTypes": ["local-model-cli", "local-model-server", "hosted-model-endpoint"],
-    "includeSampleModel": false,
+    "includeSampleModel": true,
     "skipPrompts": false
   },
   "validation": {

package/infra/ci-harness/buildspec.yml

@@ -40,6 +40,10 @@ phases:
       - REGISTER_DURATION=0
       - REGISTER_LOG_POINTER=""
       - REGISTER_ERROR_SUMMARY=""
+      - ADAPTER_TEST_STATUS="skip"
+      - ADAPTER_TEST_DURATION=0
+      - ADAPTER_TEST_LOG_POINTER=""
+      - ADAPTER_TEST_ERROR_SUMMARY=""
       - TEARDOWN_STATUS="skip"
       - TEARDOWN_DURATION=0
       - TEARDOWN_LOG_POINTER=""
@@ -182,6 +186,54 @@ phases:
         fi
       - rm -f "$STAGE_STDERR_FILE"
 
+      # --- Stage: Adapter_Test (only if do/adapters/ has .conf files) ---
+      - echo "=== Stage: Adapter_Test ==="
+      - STAGE_START=$(date +%s)
+      - ADAPTER_TEST_LOG_POINTER="$LOG_POINTER_PREFIX"
+      - STAGE_STDERR_FILE=$(mktemp)
+      - |
+        if [ -n "$FIRST_FAILURE" ]; then
+          echo "Skipping Adapter_Test stage due to prior failure in $FIRST_FAILURE"
+          ADAPTER_TEST_STATUS="skip"
+          ADAPTER_TEST_DURATION=0
+        else
+          cd /tmp/ci-project
+          ADAPTER_CONFS=$(find do/adapters -name '*.conf' 2>/dev/null | grep -v '.gitkeep' || true)
+          if [ -z "$ADAPTER_CONFS" ]; then
+            echo "No adapter configs found in do/adapters/ — skipping"
+            ADAPTER_TEST_STATUS="skip"
+            ADAPTER_TEST_DURATION=0
+          else
+            (
+              set -e
+              cd /tmp/ci-project
+              for conf in do/adapters/*.conf; do
+                [ -f "$conf" ] || continue
+                [[ "$(basename "$conf")" == ".gitkeep" ]] && continue
+                ADAPTER_NAME=$(basename "$conf" .conf)
+                echo "Testing adapter: ${ADAPTER_NAME}"
+                # Source to get weights URI
+                source "$conf"
+                ./do/adapter add "${ADAPTER_NAME}" --weights "${ADAPTER_WEIGHTS_URI}"
+                ./do/test --ic "${ADAPTER_NAME}"
+                ./do/adapter remove "${ADAPTER_NAME}"
+              done
+            ) 2>"$STAGE_STDERR_FILE"; STAGE_EXIT=$?
+            STAGE_END=$(date +%s)
+            ADAPTER_TEST_DURATION=$((STAGE_END - STAGE_START))
+            if [ "$STAGE_EXIT" -eq 0 ]; then
+              ADAPTER_TEST_STATUS="pass"
+              echo "Adapter_Test stage passed in ${ADAPTER_TEST_DURATION}s"
+            else
+              ADAPTER_TEST_STATUS="fail"
+              ADAPTER_TEST_ERROR_SUMMARY=$(tail -c 500 "$STAGE_STDERR_FILE" | tr -d '\000' | tr '"' "'" | tr '\n' ' ')
+              FIRST_FAILURE="adapter_test"
+              echo "Adapter_Test stage FAILED (exit code $STAGE_EXIT) in ${ADAPTER_TEST_DURATION}s"
+            fi
+          fi
+        fi
+      - rm -f "$STAGE_STDERR_FILE"
+
       # --- Stage: Register (placeholder) ---
       - echo "=== Stage: Register ==="
       - STAGE_START=$(date +%s)
@@ -260,6 +312,7 @@ phases:
             validate)    FINAL_ERROR_MESSAGE="$VALIDATE_ERROR_SUMMARY" ;;
             build)       FINAL_ERROR_MESSAGE="$BUILD_ERROR_SUMMARY" ;;
             deploy_test) FINAL_ERROR_MESSAGE="$DEPLOY_TEST_ERROR_SUMMARY" ;;
+            adapter_test) FINAL_ERROR_MESSAGE="$ADAPTER_TEST_ERROR_SUMMARY" ;;
             register)    FINAL_ERROR_MESSAGE="$REGISTER_ERROR_SUMMARY" ;;
             *)           FINAL_ERROR_MESSAGE="Unknown failure stage" ;;
           esac
@@ -272,6 +325,7 @@ phases:
         ESCAPED_VALIDATE_ERROR=$(printf '%s' "$VALIDATE_ERROR_SUMMARY" | sed 's/\\/\\\\/g; s/"/\\"/g')
         ESCAPED_BUILD_ERROR=$(printf '%s' "$BUILD_ERROR_SUMMARY" | sed 's/\\/\\\\/g; s/"/\\"/g')
         ESCAPED_DEPLOY_TEST_ERROR=$(printf '%s' "$DEPLOY_TEST_ERROR_SUMMARY" | sed 's/\\/\\\\/g; s/"/\\"/g')
+        ESCAPED_ADAPTER_TEST_ERROR=$(printf '%s' "$ADAPTER_TEST_ERROR_SUMMARY" | sed 's/\\/\\\\/g; s/"/\\"/g')
         ESCAPED_REGISTER_ERROR=$(printf '%s' "$REGISTER_ERROR_SUMMARY" | sed 's/\\/\\\\/g; s/"/\\"/g')
         ESCAPED_TEARDOWN_ERROR=$(printf '%s' "$TEARDOWN_ERROR_SUMMARY" | sed 's/\\/\\\\/g; s/"/\\"/g')
         ESCAPED_FINAL_ERROR=$(printf '%s' "$FINAL_ERROR_MESSAGE" | sed 's/\\/\\\\/g; s/"/\\"/g')
@@ -314,6 +368,12 @@ phases:
                   \"logPointer\": {\"S\": \"$DEPLOY_TEST_LOG_POINTER\"},
                   \"errorSummary\": {\"S\": \"$ESCAPED_DEPLOY_TEST_ERROR\"}
                 }},
+                \"adapter_test\": {\"M\": {
+                  \"status\": {\"S\": \"$ADAPTER_TEST_STATUS\"},
+                  \"durationSeconds\": {\"N\": \"$ADAPTER_TEST_DURATION\"},
+                  \"logPointer\": {\"S\": \"$ADAPTER_TEST_LOG_POINTER\"},
+                  \"errorSummary\": {\"S\": \"$ESCAPED_ADAPTER_TEST_ERROR\"}
+                }},
                 \"register\": {\"M\": {
                   \"status\": {\"S\": \"$REGISTER_STATUS\"},
                   \"durationSeconds\": {\"N\": \"$REGISTER_DURATION\"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/ml-container-creator",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Generator for SageMaker AI BYOC paradigm for predictive inference use-cases.",
   "type": "module",
   "main": "src/app.js",
@@ -111,6 +111,8 @@
     "tinyglobby": "^0.2.16"
   },
   "devDependencies": {
+    "@aws-sdk/client-sagemaker": "^3.700.0",
+    "@aws-sdk/client-service-quotas": "^3.700.0",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "eslint": "^8.57.0",
     "fast-check": "^4.5.2",

package/servers/README.md

@@ -15,7 +15,12 @@ servers/
 │   ├── test.js                 # Standalone tests (node test.js)
 │   ├── package.json
 │   └── LICENSE
-└── region-picker/              # AWS region suggestion server
+├── region-picker/              # AWS region suggestion server
+│   ├── index.js                # MCP server entry point
+│   ├── test.js                 # Standalone tests (node test.js)
+│   ├── package.json
+│   └── LICENSE
+└── endpoint-picker/            # SageMaker endpoint discovery server
     ├── index.js                # MCP server entry point
     ├── test.js                 # Standalone tests (node test.js)
     ├── package.json
@@ -74,6 +79,39 @@ Suggests AWS regions for SageMaker deployments based on a search term. Filters t
 }
 ```
 
+### endpoint-picker
+
+Discovers InService SageMaker real-time endpoints with available GPU capacity for attaching new inference components. Uses `ListEndpoints`, `DescribeEndpoint`, and `ListInferenceComponents` to calculate available capacity.
+
+**Discover mode:** Queries the SageMaker API using a 3-strategy credential fallback (explicit profile → default chain → detect profiles). No static mode — always requires AWS credentials.
+
+**Tool:** `get_inference_endpoints`
+
+| Input Field | Type | Description |
+|-------------|------|-------------|
+| `parameters` | `string[]` | Must include `"endpointName"` to get results |
+| `limit` | `number` | Max endpoints to return (default: 10) |
+| `context` | `object` | `awsRegion`, `awsProfile`, `deploymentTarget` (must be `realtime-inference`) |
+
+**Example response:**
+
+```json
+{
+  "values": { "endpointName": "my-endpoint-1234567890" },
+  "choices": { "endpointName": ["my-endpoint-1234567890", "prod-llm-endpoint"] },
+  "metadata": {
+    "my-endpoint-1234567890": {
+      "variantName": "AllTraffic",
+      "instanceType": "ml.g6e.48xlarge",
+      "instanceCount": 1,
+      "icCount": 2,
+      "availableGpus": 4,
+      "hasInstancePools": false
+    }
+  }
+}
+```
+
 ## Usage
 
 ### Adding a Bundled Server
@@ -297,6 +335,7 @@ The Bedrock API didn't respond within 10 seconds. This usually means network con
 ```bash
 node servers/region-picker/test.js
 node servers/instance-recommender/test.js
+node servers/endpoint-picker/test.js
 ```
 
 ### Smart Mode Not Activating
@@ -313,6 +352,7 @@ Each server has standalone tests that run without AWS credentials or network acc
 # Run individual server tests
 node servers/region-picker/test.js
 node servers/instance-recommender/test.js
+node servers/endpoint-picker/test.js
 
 # Run all server tests from the project root
 npm run test:servers

package/servers/instance-sizer/index.js

@@ -26,7 +26,8 @@ import { fileURLToPath } from 'node:url'
 import { resolve, dirname } from 'node:path'
 import { resolveModelMetadata } from './lib/model-resolver.js'
 import { estimateVram } from './lib/vram-estimator.js'
-import { filterAndRankInstances } from './lib/instance-ranker.js'
+import { filterAndRankInstances, applyAvailabilityRanking } from './lib/instance-ranker.js'
+import { QuotaResolver } from './lib/quota-resolver.js'
 import { queryBedrock } from '../lib/bedrock-client.js'
 
 // ── Path setup ───────────────────────────────────────────────────────────────
@@ -379,6 +380,44 @@ async function handleGetInstanceRecommendation(params) {
         { limit }
     )
 
+    // Step 3a: Quota & availability filtering (discover mode only)
+    let preQuotaFilterCount = 0
+    let allFilteredByQuota = false
+    let preQuotaRecommendations = []
+    if (DISCOVER_MODE && recommendations.length > 0) {
+        try {
+            const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION || BEDROCK_REGION
+            const quotaResolver = new QuotaResolver(region)
+
+            const instanceTypes = recommendations.map(r => r.instanceType)
+            const [quotas, reservations, ftps] = await Promise.allSettled([
+                quotaResolver.getQuotaHeadroom(instanceTypes),
+                quotaResolver.getCapacityReservations(),
+                quotaResolver.getTrainingPlans()
+            ])
+
+            preQuotaFilterCount = recommendations.length
+            preQuotaRecommendations = [...recommendations]
+            recommendations = applyAvailabilityRanking(
+                recommendations,
+                quotas.status === 'fulfilled' ? quotas.value : null,
+                reservations.status === 'fulfilled' ? reservations.value : null,
+                ftps.status === 'fulfilled' ? ftps.value : null
+            )
+            if (recommendations.length === 0 && preQuotaFilterCount > 0) {
+                allFilteredByQuota = true
+                // Restore pre-filter recommendations so user can see compatible instances
+                // and request quota increases for the ones they want
+                recommendations = preQuotaRecommendations
+                log(`All ${preQuotaFilterCount} instances filtered by zero-quota — restoring unfiltered list`)
+            }
+        } catch (err) {
+            // Graceful degradation: if credentials are missing or any unexpected
+            // error occurs, skip quota filtering and continue with unfiltered results
+            log(`Quota resolution skipped: ${err.message}`)
+        }
+    }
+
     // Step 3b: If instanceSearch is also provided, further filter by tags
     if (instanceSearch && recommendations.length > 0) {
         const searchMatches = new Set(searchInstancesByTag(instanceSearch, effectiveCatalog, { limit: 100 }))
@@ -480,7 +519,8 @@ async function handleGetInstanceRecommendation(params) {
                     vramBreakdown: vramEstimate.breakdown,
                     recommendations: finalRecommendations,
                     source: modelMetadata.source,
-                    smartModeUsed
+                    smartModeUsed,
+                    allFilteredByQuota
                 }
             })
         }]

package/servers/instance-sizer/lib/instance-ranker.js

@@ -31,14 +31,20 @@ const GPU_MEMORY_MAP = {
  */
 const COST_TIER_MAP = {
     'g4dn': 'low',
+    'g4ad': 'low',
     'inf2': 'low',
     'g5': 'medium',
     'g6': 'medium',
+    'g6e': 'medium',
+    'g7e': 'medium',
     'trn1': 'medium',
     'p3': 'high',
     'p4d': 'high',
     'p4de': 'high',
-    'p5': 'high'
+    'p5': 'high',
+    'p5e': 'high',
+    'p5en': 'high',
+    'p6': 'high'
 }
 
 /**
@@ -56,15 +62,21 @@ const COST_TIER_WEIGHT = {
  * Lower is newer (sorted first). Newer generations offer better perf/$.
  */
 const GENERATION_WEIGHT = {
-    'g6': 1,
-    'p5': 1,
-    'trn1': 2,
-    'inf2': 2,
-    'g5': 3,
-    'p4de': 4,
-    'p4d': 4,
-    'p3': 5,
-    'g4dn': 6
+    'g7e': 1,
+    'p6': 1,
+    'g6e': 2,
+    'p5e': 2,
+    'p5en': 2,
+    'g6': 3,
+    'p5': 3,
+    'trn1': 3,
+    'inf2': 3,
+    'g5': 4,
+    'p4de': 5,
+    'p4d': 5,
+    'p3': 6,
+    'g4dn': 7,
+    'g4ad': 7
 }
 
 /**
@@ -257,8 +269,99 @@ const filterAndRankInstances = (vramRequired, instanceCatalog, options = {}) =>
     return candidates.slice(0, limit)
 }
 
+// ── Availability Ranking ─────────────────────────────────────────────────────
+
+/**
+ * Priority weights for capacity types used in availability ranking.
+ * Lower value = higher priority (sorted first).
+ */
+const CAPACITY_TYPE_PRIORITY = {
+    reserved: 0,
+    ftp: 1,
+    'on-demand': 2
+}
+
+/**
+ * Annotate, filter, and re-rank instance recommendations based on
+ * quota headroom, capacity reservations, and Flexible Training Plans.
+ *
+ * Each recommendation is annotated with:
+ * - capacityType: 'reserved' | 'ftp' | 'on-demand'
+ * - quotaStatus: 'available' | 'limited' | 'zero-quota'
+ * - reservationInfo: object (when capacityType is 'reserved')
+ * - ftpInfo: object (when capacityType is 'ftp')
+ *
+ * Instances with quotaStatus === 'zero-quota' are filtered out.
+ * Sort order: reserved → FTP → on-demand, preserving existing order within tiers.
+ *
+ * When any input signal is null (API failure), that signal is skipped
+ * and the function degrades gracefully.
+ *
+ * @param {object[]} recommendations - Ranked instance recommendations from filterAndRankInstances
+ * @param {Map|null} quotas - Map: instanceType → { quota, deployed, headroom }, or null
+ * @param {Map|null} reservations - Map: instanceType → { reservationId, count, expiresAt }, or null
+ * @param {Map|null} ftps - Map: instanceType → { planName, remainingCapacity, expiresAt }, or null
+ * @returns {object[]} Filtered and re-ranked recommendations
+ */
+const applyAvailabilityRanking = (recommendations, quotas, reservations, ftps) => {
+    if (!recommendations || recommendations.length === 0) {
+        return []
+    }
+
+    // If all signals are null (all API calls failed), return unmodified
+    if (!quotas && !reservations && !ftps) {
+        return recommendations
+    }
+
+    // Annotate each recommendation with capacityType and quotaStatus
+    for (const rec of recommendations) {
+        rec.capacityType = 'on-demand'
+        rec.quotaStatus = 'available'
+
+        if (reservations?.has(rec.instanceType)) {
+            rec.capacityType = 'reserved'
+            rec.reservationInfo = reservations.get(rec.instanceType)
+            rec.reservationType = 'training-plan'
+        } else if (ftps?.has(rec.instanceType)) {
+            rec.capacityType = 'ftp'
+            rec.ftpInfo = ftps.get(rec.instanceType)
+        }
+
+        // quotaStatus applies to all instances regardless of capacityType
+        if (quotas) {
+            const q = quotas.get(rec.instanceType)
+            if (q && q.headroom === 0) {
+                rec.quotaStatus = 'zero-quota'
+            } else if (q && q.headroom < 2) {
+                rec.quotaStatus = 'limited'
+            }
+            if (q) {
+                rec.quotaHeadroom = q.headroom
+                rec.quotaDeployed = q.deployed
+                rec.quotaLimit = q.quota
+            }
+        }
+    }
+
+    // Filter out zero-quota instances (but never filter reserved/FTP — you have the capacity)
+    const filtered = recommendations.filter(r =>
+        r.quotaStatus !== 'zero-quota' || r.capacityType === 'reserved' || r.capacityType === 'ftp'
+    )
+
+    // Sort: reserved first, then FTP, then on-demand (preserve existing order within tier)
+    filtered.sort((a, b) => {
+        const pa = CAPACITY_TYPE_PRIORITY[a.capacityType] ?? 2
+        const pb = CAPACITY_TYPE_PRIORITY[b.capacityType] ?? 2
+        if (pa !== pb) return pa - pb
+        return 0
+    })
+
+    return filtered
+}
+
 export {
     filterAndRankInstances,
+    applyAvailabilityRanking,
     getPerGpuMemoryGb,
     getCostTier,
     effectiveVram,
@@ -266,5 +369,6 @@ export {
     COST_TIER_MAP,
     COST_TIER_WEIGHT,
     GENERATION_WEIGHT,
+    CAPACITY_TYPE_PRIORITY,
     TP_OVERHEAD_PER_GPU
 }