fix: validate Meilisearch provider readiness

.changeset/search-meilisearch-readiness.md

@@ -0,0 +1,5 @@
+---
+"@croco/search-meilisearch": patch
+---
+
+Meilisearch search now publishes deterministic tenant-safe conformance, upstream Problem normalization, diagnostics, and env-gated live-smoke evidence before beta maturity.

README.md

@@ -391,8 +391,8 @@ Adapter 경계와 공식 우선순위, compatibility certification checklist는
 | 상태                | 의미                                | 전체 public 패키지 수 |
 | ------------------- | ----------------------------------- | --------------------: |
 | 🟢 production-ready | 안정화, 적극 사용 권장              |                    24 |
-| 🟡 beta             | 기능 완성, 실사용 검증 중           |                    68 |
-| 🔴 alpha/WIP        | 개발 중, 사용 시 주의 필요          |                    17 |
+| 🟡 beta             | 기능 완성, 실사용 검증 중           |                    69 |
+| 🔴 alpha/WIP        | 개발 중, 사용 시 주의 필요          |                    16 |
 | ⚠️ deprecated       | 대체 패키지 존재, 마이그레이션 권장 |                     0 |
 
 ### Extension & Adapter Matrix
@@ -427,7 +427,7 @@ Runtime columns: Node는 장기 실행 서버/CLI, Lambda는 서버리스 함수
 | `@croco/onboarding-drizzle`      | Onboarding      | Drizzle repository                   | yes  | yes    | -       | -        | database connection supplied by app                                                 | -                                                               | onboarding state persistence<br>step completion storage                                                                                                                                   | 🟡 beta      | has package tests |
 | `@croco/ratelimit-upstash`       | Rate limiting   | Upstash Redis rate-limit store       | yes  | yes    | -       | -        | UPSTASH_REDIS_REST_URL<br>UPSTASH_REDIS_REST_TOKEN                                  | @upstash/redis                                                  | sliding window<br>token bucket<br>fixed window<br>Lua atomicity<br>shared conformance<br>redacted upstream Problems                                                                       | 🔴 alpha/WIP | has package tests |
 | `@croco/search-drizzle`          | Search          | Drizzle search index                 | yes  | yes    | -       | -        | database connection supplied by app                                                 | drizzle-orm                                                     | search document persistence<br>tenant-aware lookup                                                                                                                                        | 🟡 beta      | has package tests |
-| `@croco/search-meilisearch`      | Search          | Meilisearch engine                   | yes  | yes    | -       | -        | MEILISEARCH_HOST<br>MEILISEARCH_API_KEY                                             | -                                                               | indexing<br>search<br>tenant tokens                                                                                                                                                       | 🔴 alpha/WIP | has package tests |
+| `@croco/search-meilisearch`      | Search          | Meilisearch engine                   | yes  | yes    | -       | -        | MEILISEARCH_HOST<br>MEILISEARCH_API_KEY                                             | -                                                               | indexing<br>search<br>tenant tokens<br>search conformance<br>safe diagnostics<br>env-gated live smoke                                                                                     | 🟡 beta      | has package tests |
 | `@croco/storage-cloudflare`      | Storage         | Cloudflare Images provider           | yes  | yes    | -       | -        | CLOUDFLARE_ACCOUNT_ID<br>CLOUDFLARE_API_TOKEN<br>CLOUDFLARE_ACCOUNT_HASH            | -                                                               | image upload<br>transform URLs<br>upload intents<br>signed URLs<br>storage conformance<br>diagnostics<br>optional live smoke                                                              | 🔴 alpha/WIP | has package tests |
 | `@croco/storage-cloudinary`      | Storage         | Cloudinary provider                  | yes  | yes    | -       | -        | CLOUDINARY_CLOUD_NAME<br>CLOUDINARY_API_KEY<br>CLOUDINARY_API_SECRET                | -                                                               | file upload<br>transform URLs<br>upload intents<br>retry<br>storage conformance<br>diagnostics<br>optional live smoke                                                                     | 🟡 beta      | has package tests |
 | `@croco/storage-r2`              | Storage         | Cloudflare R2 S3-compatible provider | yes  | yes    | -       | -        | R2_ACCOUNT_ID<br>R2_ACCESS_KEY_ID<br>R2_SECRET_ACCESS_KEY<br>R2_BUCKET              | -                                                               | put/get/delete<br>signed URLs<br>stream reads<br>retry<br>safe diagnostics<br>env-gated live smoke                                                                                        | 🟡 beta      | has package tests |
@@ -553,6 +553,7 @@ Runtime columns: Node는 장기 실행 서버/CLI, Lambda는 서버리스 함수
 | `@croco/metering-drizzle`              | Provider     | `packages/metering-drizzle`              | README, API, tests |
 | `@croco/onboarding-drizzle`            | Provider     | `packages/onboarding-drizzle`            | README, API, tests |
 | `@croco/search-drizzle`                | Provider     | `packages/search-drizzle`                | README, API, tests |
+| `@croco/search-meilisearch`            | Provider     | `packages/search-meilisearch`            | README, API, tests |
 | `@croco/storage-cloudinary`            | Provider     | `packages/storage-cloudinary`            | README, API, tests |
 | `@croco/storage-r2`                    | Provider     | `packages/storage-r2`                    | README, API, tests |
 | `@croco/architecture-policy`           | Tooling      | `packages/architecture-policy`           | README, API, tests |
@@ -583,7 +584,6 @@ Runtime columns: Node는 장기 실행 서버/CLI, Lambda는 서버리스 함수
 | `@croco/metrics-billing`      | Provider     | `packages/metrics-billing`      | README, API, tests |
 | `@croco/notifications-resend` | Provider     | `packages/notifications-resend` | README, API, tests |
 | `@croco/ratelimit-upstash`    | Provider     | `packages/ratelimit-upstash`    | README, API, tests |
-| `@croco/search-meilisearch`   | Provider     | `packages/search-meilisearch`   | README, API, tests |
 | `@croco/storage-cloudflare`   | Provider     | `packages/storage-cloudflare`   | README, API, tests |
 | `@croco/tasks-qstash`         | Provider     | `packages/tasks-qstash`         | README, API, tests |
 | `@croco/triggers-qstash`      | Provider     | `packages/triggers-qstash`      | README, API, tests |

docs/package-catalog.json

@@ -237,6 +237,7 @@
         "protocols-trpc",
         "rpc-codegen",
         "search-drizzle",
+        "search-meilisearch",
         "storage-cloudinary",
         "storage-core",
         "storage-r2",
@@ -266,7 +267,6 @@
         "metrics-billing",
         "notifications-resend",
         "ratelimit-upstash",
-        "search-meilisearch",
         "storage-cloudflare",
         "tasks-qstash",
         "triggers-qstash"
@@ -601,7 +601,14 @@
         "adapter": "Meilisearch engine",
         "runtimes": ["node", "lambda"],
         "requiredEnv": ["MEILISEARCH_HOST", "MEILISEARCH_API_KEY"],
-        "features": ["indexing", "search", "tenant tokens"]
+        "features": [
+          "indexing",
+          "search",
+          "tenant tokens",
+          "search conformance",
+          "safe diagnostics",
+          "env-gated live smoke"
+        ]
       },
       "storage-cloudflare": {
         "domain": "Storage",

docs/package-docs-report.md

@@ -52,8 +52,8 @@ None.
 | Maturity            | Packages |
 | ------------------- | -------: |
 | 🟢 production-ready |       24 |
-| 🟡 beta             |       68 |
-| 🔴 alpha/WIP        |       17 |
+| 🟡 beta             |       69 |
+| 🔴 alpha/WIP        |       16 |
 | ⚠️ deprecated       |        0 |
 
 ## Extension Matrix

docs/problem-code-registry.json

@@ -1,6 +1,6 @@
 {
   "version": "croco.problem-code-registry.v1",
-  "problemCount": 388,
+  "problemCount": 393,
   "problems": [
     {
       "code": "ACCESS_DENIED",
@@ -7886,6 +7886,114 @@
         }
       ]
     },
+    {
+      "code": "search-meilisearch/index-not-found",
+      "category": "NotFound",
+      "status": 404,
+      "title": "Not Found",
+      "cookbookPath": "/reference/problem-recovery-cookbook/#search-meilisearch-index-not-found",
+      "recovery": {
+        "cause": "The requested resource or route-visible record does not exist.",
+        "userAction": "Verify the identifier and refresh the resource list before retrying.",
+        "operatorAction": "Confirm tenant scoping, data retention, and backing-store lookup behavior.",
+        "retryability": "not-retryable",
+        "redactionPolicy": "public",
+        "telemetry": {
+          "eventName": "croco.problem.info",
+          "severity": "info",
+          "attributes": ["problem.code", "problem.category", "problem.status"]
+        }
+      },
+      "sources": [
+        {
+          "file": "packages/search-meilisearch/src/libs/problems/MeilisearchProblems.ts",
+          "line": 80,
+          "column": 5,
+          "kind": "problem-constructor"
+        }
+      ]
+    },
+    {
+      "code": "search-meilisearch/invalid-request",
+      "category": "ValidationError",
+      "status": 422,
+      "title": "Validation Error",
+      "cookbookPath": "/reference/problem-recovery-cookbook/#search-meilisearch-invalid-request",
+      "recovery": {
+        "cause": "The request or generated contract failed schema or semantic validation.",
+        "userAction": "Fix the invalid fields and retry with schema-conformant input.",
+        "operatorAction": "Inspect schema diagnostics, generated contracts, and validation metadata.",
+        "retryability": "not-retryable",
+        "redactionPolicy": "public",
+        "telemetry": {
+          "eventName": "croco.problem.info",
+          "severity": "info",
+          "attributes": ["problem.code", "problem.category", "problem.status"]
+        }
+      },
+      "sources": [
+        {
+          "file": "packages/search-meilisearch/src/libs/problems/MeilisearchProblems.ts",
+          "line": 60,
+          "column": 5,
+          "kind": "problem-constructor"
+        }
+      ]
+    },
+    {
+      "code": "search-meilisearch/missing-config",
+      "category": "InternalServerError",
+      "status": 500,
+      "title": "Internal Server Error",
+      "cookbookPath": "/reference/problem-recovery-cookbook/#search-meilisearch-missing-config",
+      "recovery": {
+        "cause": "Croco or an upstream dependency failed after accepting the request.",
+        "userAction": "Retry later only when the operation is idempotent or the caller owns retry safety.",
+        "operatorAction": "Use traces, logs, and upstream diagnostics to isolate the failing boundary.",
+        "retryability": "conditional",
+        "redactionPolicy": "operator-only",
+        "telemetry": {
+          "eventName": "croco.problem.error",
+          "severity": "error",
+          "attributes": ["problem.code", "problem.category", "problem.status"]
+        }
+      },
+      "sources": [
+        {
+          "file": "packages/search-meilisearch/src/libs/problems/MeilisearchProblems.ts",
+          "line": 39,
+          "column": 5,
+          "kind": "problem-constructor"
+        }
+      ]
+    },
+    {
+      "code": "search-meilisearch/retryable-upstream",
+      "category": "InternalServerError",
+      "status": 500,
+      "title": "Internal Server Error",
+      "cookbookPath": "/reference/problem-recovery-cookbook/#search-meilisearch-retryable-upstream",
+      "recovery": {
+        "cause": "Croco or an upstream dependency failed after accepting the request.",
+        "userAction": "Retry later only when the operation is idempotent or the caller owns retry safety.",
+        "operatorAction": "Use traces, logs, and upstream diagnostics to isolate the failing boundary.",
+        "retryability": "conditional",
+        "redactionPolicy": "operator-only",
+        "telemetry": {
+          "eventName": "croco.problem.error",
+          "severity": "error",
+          "attributes": ["problem.code", "problem.category", "problem.status"]
+        }
+      },
+      "sources": [
+        {
+          "file": "packages/search-meilisearch/src/libs/problems/MeilisearchProblems.ts",
+          "line": 100,
+          "column": 5,
+          "kind": "problem-constructor"
+        }
+      ]
+    },
     {
       "code": "search-meilisearch/tenant-token-not-configured",
       "category": "InternalServerError",
@@ -7907,9 +8015,36 @@
       "sources": [
         {
           "file": "packages/search-meilisearch/src/libs/problems/MeilisearchProblems.ts",
-          "line": 7,
-          "column": 3,
-          "kind": "problem-class"
+          "line": 140,
+          "column": 5,
+          "kind": "problem-constructor"
+        }
+      ]
+    },
+    {
+      "code": "search-meilisearch/terminal-upstream",
+      "category": "InternalServerError",
+      "status": 500,
+      "title": "Internal Server Error",
+      "cookbookPath": "/reference/problem-recovery-cookbook/#search-meilisearch-terminal-upstream",
+      "recovery": {
+        "cause": "Croco or an upstream dependency failed after accepting the request.",
+        "userAction": "Retry later only when the operation is idempotent or the caller owns retry safety.",
+        "operatorAction": "Use traces, logs, and upstream diagnostics to isolate the failing boundary.",
+        "retryability": "conditional",
+        "redactionPolicy": "operator-only",
+        "telemetry": {
+          "eventName": "croco.problem.error",
+          "severity": "error",
+          "attributes": ["problem.code", "problem.category", "problem.status"]
+        }
+      },
+      "sources": [
+        {
+          "file": "packages/search-meilisearch/src/libs/problems/MeilisearchProblems.ts",
+          "line": 120,
+          "column": 5,
+          "kind": "problem-constructor"
         }
       ]
     },

packages/docs/src/content/docs/api/problems-core/src/classes/Problem.md

@@ -251,6 +251,11 @@ RFC 7807 Problem Details를 표현하는 기본 추상 에러 클래스입니다
 - [`SearchCapabilityUnavailableProblem`](/api/search-core/src/classes/searchcapabilityunavailableproblem/)
 - [`StrategyUnavailableProblem`](/api/search-core/src/classes/strategyunavailableproblem/)
 - [`TransformNotFoundProblem`](/api/search-core/src/classes/transformnotfoundproblem/)
+- [`MeilisearchIndexNotFoundProblem`](/api/search-meilisearch/src/classes/meilisearchindexnotfoundproblem/)
+- [`MeilisearchInvalidRequestProblem`](/api/search-meilisearch/src/classes/meilisearchinvalidrequestproblem/)
+- [`MeilisearchRetryableUpstreamProblem`](/api/search-meilisearch/src/classes/meilisearchretryableupstreamproblem/)
+- [`MeilisearchTerminalUpstreamProblem`](/api/search-meilisearch/src/classes/meilisearchterminalupstreamproblem/)
+- [`MissingMeilisearchConfigProblem`](/api/search-meilisearch/src/classes/missingmeilisearchconfigproblem/)
 - [`TenantTokenNotConfiguredProblem`](/api/search-meilisearch/src/classes/tenanttokennotconfiguredproblem/)
 - [`CloudflareImagesMissingConfigProblem`](/api/storage-cloudflare/src/classes/cloudflareimagesmissingconfigproblem/)
 - [`CloudflareImagesRetryableUpstreamProblem`](/api/storage-cloudflare/src/classes/cloudflareimagesretryableupstreamproblem/)
@@ -304,7 +309,7 @@ RFC 7807 Problem Details를 표현하는 기본 추상 에러 클래스입니다
 
 > `readonly` **category**: [`ProblemCategory`](/api/problems-core/src/enumerations/problemcategory/)
 
----
+***
 
 ### cause?
 
@@ -314,31 +319,31 @@ RFC 7807 Problem Details를 표현하는 기본 추상 에러 클래스입니다
 
 `Error.cause`
 
----
+***
 
 ### code
 
 > `readonly` **code**: `string`
 
----
+***
 
 ### detail?
 
 > `readonly` `optional` **detail?**: `string`
 
----
+***
 
 ### extensions?
 
 > `readonly` `optional` **extensions?**: [`ProblemExtensions`](/api/problems-core/src/type-aliases/problemextensions/)
 
----
+***
 
 ### instance?
 
 > `readonly` `optional` **instance?**: `string`
 
----
+***
 
 ### message
 
@@ -348,7 +353,7 @@ RFC 7807 Problem Details를 표현하는 기본 추상 에러 클래스입니다
 
 `Error.message`
 
----
+***
 
 ### name
 
@@ -358,7 +363,7 @@ RFC 7807 Problem Details를 표현하는 기본 추상 에러 클래스입니다
 
 `Error.name`
 
----
+***
 
 ### stack?
 
@@ -368,13 +373,13 @@ RFC 7807 Problem Details를 표현하는 기본 추상 에러 클래스입니다
 
 `Error.stack`
 
----
+***
 
 ### type
 
 > `readonly` **type**: `string`
 
----
+***
 
 ### stackTraceLimit
 
@@ -406,7 +411,7 @@ not capture any frames.
 
 `number`
 
----
+***
 
 ### title
 
@@ -428,7 +433,7 @@ not capture any frames.
 
 [`ProblemDetails`](/api/problems-core/src/type-aliases/problemdetails/)
 
----
+***
 
 ### captureStackTrace()
 
@@ -441,7 +446,7 @@ a string representing the location in the code at which
 ```js
 const myObject = {};
 Error.captureStackTrace(myObject);
-myObject.stack; // Similar to `new Error().stack`
+myObject.stack;  // Similar to `new Error().stack`
 ```
 
 The first line of the trace will be prefixed with
@@ -496,7 +501,7 @@ a();
 
 `Error.captureStackTrace`
 
----
+***
 
 ### prepareStackTrace()