docs: Add TODO comments and improve documentation for type assertions

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/foundation/core/src/repository.ts

@@ -57,6 +57,9 @@ export class ObjectRepository {
         }
 
         // Backward compatibility: if it's already an array (old format), convert to FilterNode
+        // TODO: This uses type assertion because the old code used arrays for filters
+        // but FilterNode is now an object-based AST. This should be properly converted
+        // to build FilterNode objects in a future refactoring.
         if (Array.isArray(filters)) {
             return filters as unknown as FilterNode;
         }
@@ -128,6 +131,9 @@ export class ObjectRepository {
             }
         }
 
+        // TODO: This returns an array but FilterNode is now an object-based AST.
+        // This type assertion is temporary for backward compatibility. Should be
+        // refactored to build proper FilterNode objects with type/operator/children.
         return (nodes.length === 1 ? nodes[0] : nodes) as unknown as FilterNode;
     }
 

packages/foundation/core/tsconfig.json

@@ -5,7 +5,13 @@
     "rootDir": "src"
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "../../../node_modules/@objectstack+objectql"],
+  "exclude": [
+    "node_modules", 
+    "dist", 
+    // Exclude external @objectstack/objectql package that has type incompatibilities
+    // with our stub packages during migration phase
+    "../../../node_modules/@objectstack+objectql"
+  ],
   "references": [
     { "path": "../types" }
   ]

packages/objectstack/spec/src/index.ts

@@ -257,11 +257,12 @@ export interface App {
 
 /**
  * ObjectStack Manifest
+ * Configuration manifest for ObjectStack applications
  */
 export interface ObjectStackManifest {
     /** Manifest version */
     version: string;
-    /** Manifest ID */
+    /** Unique identifier for the manifest (optional) */
     id?: string;
     /** Application info */
     app?: App;