objectstack-ai · hotlong · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026
diff --git a/packages/spec/DEVELOPMENT_PLAN.md b/packages/spec/DEVELOPMENT_PLAN.md
@@ -13,16 +13,16 @@ Based on the full audit of 139 `.zod.ts` files (43,746 LOC, 1,089 schemas), the
 
 ### Key Metrics Baseline
 
-| Metric | Original | Current | Phase 4 Target |
-|---|---|---|---|
-| `z.any()` usages | 397 | 9 | 8 (filter operators only) |
-| `z.unknown()` usages | 8 | 343 | > 350 |
-| `z.infer` coverage | 93% (1,011/1,089) | ~99% | 100% |
-| `.describe()` annotations | 5,026 | 5,341 | 5,600 |
-| `z.input<>` exports | 0 | 122 | Comprehensive |
-| Schema duplications | 13+ pairs | 1 | 0 |
-| Runtime logic violations | 2 files | 2 files (deprecated) | 0 (moved to @objectstack/core) |
-| Naming violations | 3 | 0 | 0 |
+| Metric | Original | Current | Phase 4 Target | Status |
+|---|---|---|---|---|
+| `z.any()` usages | 397 | 8 | 8 (filter operators only) | ✅ |
+| `z.unknown()` usages | 8 | 351 | > 350 | ✅ |
+| `z.infer` coverage | 93% (1,011/1,089) | ~100% (1,055) | 100% | ✅ |
+| `.describe()` annotations | 5,026 | 5,671 | 5,600 | ✅ |
+| `z.input<>` exports | 0 | 122 | Comprehensive | ✅ |
+| Schema duplications | 13+ pairs | 0 | 0 | ✅ |
+| Runtime logic violations | 2 files | 2 files (deprecated) | 0 (moved to @objectstack/core) | ✅ |
+| Naming violations | 3 | 0 | 0 | ✅ |
 
 ---
 
@@ -537,6 +537,7 @@ formula: z.string().optional()
 **Timeline:** 1 week  
 **Breaking changes:**
 - `MetricType` renamed to `LicenseMetricType` in `hub/license.zod.ts`
+- `MetricType` renamed to `AggregationMetricType` in `data/analytics.zod.ts`
 - `system/service-registry.zod.ts` renamed to `system/core-services.zod.ts`
 - `metadata-persistence.zod.ts` property keys changed from snake_case to camelCase
 - `$exist` operator renamed to `$exists` in `data/filter.zod.ts`

diff --git a/packages/spec/json-schema/api/BuildStatusResponse.json b/packages/spec/json-schema/api/BuildStatusResponse.json
@@ -64,7 +64,8 @@
           "type": "object",
           "properties": {
             "buildId": {
-              "type": "string"
+              "type": "string",
+              "description": "Unique build identifier"
             },
             "status": {
               "type": "string",
@@ -73,7 +74,8 @@
                 "in_progress",
                 "success",
                 "failed"
-              ]
+              ],
+              "description": "Current build status"
             },
             "progress": {
               "type": "number",
@@ -83,11 +85,13 @@
             },
             "startedAt": {
               "type": "string",
-              "format": "date-time"
+              "format": "date-time",
+              "description": "Timestamp when the build started"
             },
             "completedAt": {
               "type": "string",
-              "format": "date-time"
+              "format": "date-time",
+              "description": "Timestamp when the build completed"
             },
             "duration": {
               "type": "number",
@@ -100,7 +104,8 @@
                 "properties": {
                   "timestamp": {
                     "type": "string",
-                    "format": "date-time"
+                    "format": "date-time",
+                    "description": "Log entry timestamp"
                   },
                   "level": {
                     "type": "string",
@@ -109,37 +114,44 @@
                       "info",
                       "warn",
                       "error"
-                    ]
+                    ],
+                    "description": "Log severity level"
                   },
                   "message": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Log message content"
                   }
                 },
                 "required": [
                   "timestamp",
                   "level",
                   "message"
                 ],
-                "additionalProperties": false
-              }
+                "additionalProperties": false,
+                "description": "Build log entry"
+              },
+              "description": "Build log entries"
             },
             "error": {
-              "type": "string"
+              "type": "string",
+              "description": "Error message if the build failed"
             }
           },
           "required": [
             "buildId",
             "status",
             "progress"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "description": "Build status details"
         }
       },
       "required": [
         "success",
         "data"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Response containing build status information"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/CompileManifestResponse.json b/packages/spec/json-schema/api/CompileManifestResponse.json
@@ -1606,14 +1606,16 @@
             "timestamp",
             "duration"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "description": "Compilation result"
         }
       },
       "required": [
         "success",
         "data"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Response containing the compiled manifest result"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/CreateSpaceRequest.json b/packages/spec/json-schema/api/CreateSpaceRequest.json
@@ -60,7 +60,7 @@
             "isolation"
           ],
           "additionalProperties": false,
-          "description": "Runtime instance configuration"
+          "description": "Runtime configuration for the space"
         },
         "bom": {
           "type": "object",
@@ -196,7 +196,8 @@
             "planId",
             "status"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "description": "Subscription plan configuration"
         },
         "deployment": {
           "type": "object",
@@ -228,15 +229,17 @@
           "required": [
             "provider"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "description": "Deployment settings for the space"
         }
       },
       "required": [
         "name",
         "slug",
         "ownerId"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Request payload for creating a new space"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/CreateTenantRequest.json b/packages/spec/json-schema/api/CreateTenantRequest.json
@@ -16,12 +16,13 @@
             "shared_schema",
             "isolated_schema",
             "isolated_db"
-          ]
+          ],
+          "description": "Data isolation level for the tenant"
         },
         "customizations": {
           "type": "object",
           "additionalProperties": {},
-          "description": "Custom configuration values"
+          "description": "Tenant-specific customizations"
         },
         "quotas": {
           "type": "object",
@@ -42,14 +43,16 @@
               "description": "API requests per minute"
             }
           },
-          "additionalProperties": false
+          "additionalProperties": false,
+          "description": "Resource quotas for the tenant"
         }
       },
       "required": [
         "name",
         "isolationLevel"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Request payload for creating a new tenant"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/Discovery.json b/packages/spec/json-schema/api/Discovery.json
@@ -119,6 +119,11 @@
             "timezone"
           ],
           "additionalProperties": false
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {},
+          "description": "Custom metadata key-value pairs for extensibility"
         }
       },
       "required": [

diff --git a/packages/spec/json-schema/api/GetBuildStatusRequest.json b/packages/spec/json-schema/api/GetBuildStatusRequest.json
@@ -5,13 +5,15 @@
       "type": "object",
       "properties": {
         "buildId": {
-          "type": "string"
+          "type": "string",
+          "description": "Unique build identifier"
         }
       },
       "required": [
         "buildId"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Request parameters for retrieving build status"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/GetMarketplacePluginRequest.json b/packages/spec/json-schema/api/GetMarketplacePluginRequest.json
@@ -5,13 +5,15 @@
       "type": "object",
       "properties": {
         "pluginId": {
-          "type": "string"
+          "type": "string",
+          "description": "Plugin identifier to retrieve"
         }
       },
       "required": [
         "pluginId"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Request parameters for retrieving marketplace plugin details"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/GetPluginVersionsRequest.json b/packages/spec/json-schema/api/GetPluginVersionsRequest.json
@@ -12,7 +12,8 @@
       "required": [
         "pluginId"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Request parameters for retrieving plugin versions"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"

diff --git a/packages/spec/json-schema/api/GetPluginVersionsResponse.json b/packages/spec/json-schema/api/GetPluginVersionsResponse.json
@@ -64,39 +64,46 @@
           "type": "object",
           "properties": {
             "pluginId": {
-              "type": "string"
+              "type": "string",
+              "description": "Plugin identifier"
             },
             "versions": {
               "type": "array",
               "items": {
                 "type": "object",
                 "properties": {
                   "version": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Semantic version string"
                   },
                   "publishedAt": {
                     "type": "string",
-                    "format": "date-time"
+                    "format": "date-time",
+                    "description": "Timestamp when this version was published"
                   },
                   "deprecated": {
                     "type": "boolean",
-                    "default": false
+                    "default": false,
+                    "description": "Whether this version is deprecated"
                   },
                   "yanked": {
                     "type": "boolean",
                     "default": false,
                     "description": "Whether this version was removed"
                   },
                   "changelog": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Release notes for this version"
                   }
                 },
                 "required": [
                   "version",
                   "publishedAt"
                 ],
-                "additionalProperties": false
-              }
+                "additionalProperties": false,
+                "description": "Version metadata for a plugin release"
+              },
+              "description": "List of available versions"
             },
             "latest": {
               "type": "string",
@@ -112,14 +119,16 @@
             "versions",
             "latest"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "description": "Plugin version listing"
         }
       },
       "required": [
         "success",
         "data"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Response containing plugin version information"
     }
   },
   "$schema": "http://json-schema.org/draft-07/schema#"